ilysa

README

Ilysa

Ilysa is a Go library for creating Beat Saber lighting effects.

Interactive Tutorial

Ilysa by Example

Moving Pictures

• Same code for all 5 environments
• Ilysa automatically adapts to the lightIDs available in the selected environment

Getting Started

Web

If you are not sure whether Ilysa is for you, you can try Ilysa out on the web, albeit without code completion assistance. No installation required!

Click here Simple Example and click Run.

Requirements

• a working Go environment
• a working Git installation
• a code editor (these instructions are tested with Visual Studio Code and Ilysa's author uses Goland)
• a beatmap with all requisite BPM blocks placed

Go Environment

Follow the instructions at:

• Download and install
• Tutorial: Get started with Go

If successfully complete all the instructions at Tutorial: Get started with Go, you have a working Go environment.

Git Installation

If you are on:

• Windows - download and install from https://git-scm.com/downloads
• macOS - run git from Terminal to start the installer
• Linux - you don't need me

Code Editor

Visual Studio Code

Install the Go extension from the Extensions menu and follow its Quick Start instructions. Be sure to install the command line tools when prompted to do so for code assistance support.

Goland

You know what you're doing.

Vim/Emacs

You definitely know what you're doing. Get gopls support up and you should be good to go.

Something Else

You really want something that provides code assistance via gopls or something similar. If you are unsure, please try starting out with Visual Studio Code.

Beatmap

Ilysa works in BPM adjusted beats, i.e. the beat numbers displayed in MMA2 or ChroMapper. If you do not place all the required BPM blocks before starting, and add BPM blocks after writing Ilysa code, you will probably have to retime your code.

Walkthrough

⚠️ Ilysa will replace all lighting events in the selected difficulty. Please dedicate a copy of your map for use with Ilysa and make backups (you should be making backups regardless)!⚠️

Preliminaries

Create a new directory to hold your Ilysa project, then in that directory, execute the following commands:

Initialize the directory as the root of a Go project.

go mod init projectName

Download Ilysa.

go get -u github.com/shasderias/ilysa@v0.0.14

Boilerplate

New to Go? Create a file named main.go in your project directory and copy and paste the contents of examples/getting-started/main.go into it.

Compile and run your code by executing:

go run .

This will remove all lighting events from your map and add all events generated by Ilysa to it. The boilerplate code does not generate any events, so this will simply remove all existing events.

Your First Ilysa Event

Edit main.go and add the following lines after the line // -- your code goes here --

 	// -- your code goes here --
	ctx.Sequence(timer.Beat(0), func(ctx context.Context) { // generate events at beat 0
		ctx.NewLighting( // new base game lighting event
			evt.WithLight(evt.BackLasers),      // back lasers
			evt.WithLightValue(evt.LightRedOn), // red on
		)
	})

Compile and run by executing go run . and you should see a back laser, red on event at beat 0 in your beatmap.

Next Steps

Follow the examples at Ilysa by Example for a tour of Ilysa's key features.

Updating

Run in the root of your project:

go get -u github.com/shasderias/ilysa@v0.0.14

Helper Packages

Ease

The ease package implements Robert Penner's easing functions. Visualize them at https://easings.net/.

Scale

The scale package implements a few functions handy for scaling numbers:

// returns a function that scales a number from [rMin,rMax] to [tMin,tMax]
func Clamped(rMin, rMax, tMin, tMax float64) func(m float64) float64
// returns a function that scales a number from [0,1] to [tMin,tMax]
func ToUnitIntervalClamped(tMin, tMax float64) func(m float64) float64 
// returns a function that scales a number from [rMin,rMax] to [0,1]
func FromUnitIntervalClammped(rMin, rMax float64) func(m float64) float64 

Colors

The colorful package (adapted from go-colorful) implements a bunch of functions handy for working with colors.

See Ilysa by Example: Sequence and Range and Ilysa by Example: Light - Gradient to get started.

Is Ilysa for me?

Advanced Beat Saber lighting knowledge and intermediate computer skills required.

Ilysa may be for you if:

• you are experienced with lighting, can't code, but want to get started with scripting lights; starting with Ilysa is probably easier than trying to cobble together code from scratch;
• you are already scripting lights, and want a little more structure or help with dealing with the more tedious parts; or
• you are experienced with lighting, can code and want to raise the bar; the author thinks there are interesting things that can be done to make doing good lighting easier - check out the Light interface.

Ilysa is not for you if:

• you have never placed a Chroma event in ChroMapper;
• _eventType and _eventValue don't mean anything to you; or
• a command prompt scares you.

Ilysa ...

• may not give better results than handlighting, it only makes actualizing complicated effects easy;
• may not be easier than handlighting (the converse is probably true);
• is not an autolighter - results directly proportionate to user's skill;
• does not generate any other beatmap elements (for walls, you probably want spookyGh0st's Beatwalls).

Do I need to know Go? Programming?

Ilysa is designed to be somewhat usable by a non-programmer (actual results may vary). You can probably achieve basic results by copy/pasting code and tweaking values.

If you want to achieve novel effects, you'll need at least a rudimentary understanding of Go.

If you can already program in another language, Go should be a snap. You will most likely be able to start just by referring to the examples at Ilysa by Example. You can also take a stroll through A Tour of Go if you want.

If you have no programming experience, Go is an easy language to learn. Try taking A Tour of Go. If you can make it to the section on Methods, you should be good to go.

Tips and Tricks

Visual Studio Code Keyboard Shortcuts

• Ctrl-Shift-Space - display function arguments
• Ctrl-Space - autocomplete

Resources

• https://www.desmos.com/calculator

Credits

• Alice (Alice#5792) for lighting advice and being a sounding board. Check her out on Twitch!
• Andrey Sitnik and Ivan Solovev for the excellent visualizations of Robert Penner's easing equations at https://easings.net/.
• George McGinley Smith for the implementation of Robert Penner's easing equations in the jquery.easing library.
• Lucas Beyer, Bastien Dejean (@baskerville), Phil Kulak (@pkulak), Christian Muehlhaeuser (@muesli), makeworld ( @makeworld-the-better-one) and the other contributors to the go-colorful library, used under the MIT License.
• Pennock Tech, LLC for the swallowjson library, used under the MIT License.
• Robert Penner for the original easing functions. Find out more here.
• Top_Cat (Top_Cat#1961) for the Beat Saber environment definition files at https://github.com/Top-Cat/bs-env.

Documentation

Index

• type EventCustomData
• type Map
• type Project
  • func New(bsMap Map) *Project
  • func (p *Project) AddEvents(events ...evt.Event)
  • func (p *Project) Append() error
  • func (p *Project) BOffset(offset float64) context.Context
  • func (p *Project) Dump() error
  • func (p *Project) Events() *[]evt.Event
  • func (p *Project) FilterEvents(f func(e evt.Event) bool) *[]evt.Event
  • func (p *Project) GenerateGradientReference(path string) error
  • func (p *Project) MapEvents(f func(e evt.Event) evt.Event)
  • func (p *Project) MaxLightID(t evt.LightType) int
  • func (p *Project) Save() error
  • func (p *Project) SaveDev() error
  • func (p *Project) SaveProd() error

Types

type EventCustomData

type EventCustomData struct {
	IlysaDev bool                   `json:"ilysaDev"`
	Rest     map[string]interface{} `json:"-"`
}

type Map

type Map interface {
	ActiveDifficultyProfile() *beatsaber.EnvProfile
	AppendEvents([]beatsaber.Event) error
	Events() []beatsaber.Event
	SaveEvents([]beatsaber.Event) error
	SetActiveDifficulty(c beatsaber.Characteristic, difficulty beatsaber.BeatmapDifficulty) error
	UnscaleTime(beat float64) beatsaber.Time
}

type Project

type Project struct {
	Map
	context.Context
	// contains filtered or unexported fields
}

func New

func New(bsMap Map) *Project

func (*Project) AddEvents

func (p *Project) AddEvents(events ...evt.Event)

func (*Project) Append

func (p *Project) Append() error

func (*Project) BOffset

func (p *Project) BOffset(offset float64) context.Context

func (*Project) Dump

func (p *Project) Dump() error

func (*Project) Events

func (p *Project) Events() *[]evt.Event

func (*Project) FilterEvents

func (p *Project) FilterEvents(f func(e evt.Event) bool) *[]evt.Event

func (*Project) GenerateGradientReference

func (p *Project) GenerateGradientReference(path string) error

GenerateGradientReference generates a PNG with all gradients declared at the top level and saves it to path. Each gradient is labelled with its name. Useful as a reference.

GenerateGradientReference only works on the machine the program is compiled on.

func (*Project) MapEvents

func (p *Project) MapEvents(f func(e evt.Event) evt.Event)

func (*Project) MaxLightID

func (p *Project) MaxLightID(t evt.LightType) int

func (*Project) Save

func (p *Project) Save() error

func (*Project) SaveDev

func (p *Project) SaveDev() error

func (*Project) SaveProd

func (p *Project) SaveProd() error