help

(help define-actor)
(help!)                 ; quick reference
(list-commands)
(tutorial)

keyboard shortcuts

eval line

shift+enter

eval block

ctrl+enter

toggle control window

ctrl+p

toggle mouse cursor

ctrl+m

animations

(assets-path)
(assets-path-set! "user://assets/animations")        ; default
(assets-path-set! "/home/you/Documents/animations")  ; MacOS + Linux
(assets-path-set! "C:/Projects/Animations")          ; Windows
(list-assets)   ; available on disk ready to load
(define-animation some-anim)            ; folder named "some-anim" in the assets folder
(define-animation my-anim "other-anim") ; load "other-anim" but name it 'my-animation'
(list-animations)                       ; loaded to memory

sequencing animations

(add-animation-sequence! foo anim1 anim2)        ; play anim2 after anim1
(add-animation-sequence! foo anim2 anim1 anim2)  ; play anim1 or anim2 after anim2
(remove-animation-sequence! foo anim2)           ; loop anim2
(list-animation-sequences foo)

executing code with animations

(on-actor-animation-finished foo            ; execute code every time `foo` loops the animation
    (speed! foo (random-range 1.0 2.0))     ; change speed on every animation loop
    (opacity! foo (random-range 0.1 1)))    ; change opacity on every animation loop
(on-actor-animation-finished foo)   ; reset - do nothing when `foo` loops the animation

actors

add / remove

(define-actor foo some-anim)	        ; create an actor with a name + loaded animation
(define-actor foo some-anim LAYER_2)	; add to group (LAYER_1-4, BG, FG)
(actor-find "foo")		                ; returns the actor object by NAME
(duplicate! foo bar)
(remove! foo)
(list-actors)		                    ; prints actor names
(animation! foo "another-animation")    ; change the animation

play/stop

(play! foo)
(play-backwards! foo)
(stop! foo)
(speed! foo 0.5)
(loop! foo)		; loop an ACTOR's animation
(noloop! foo)       ; play an ACTOR's animation once and stop at the last frame
(pingpong! foo)     ; play an ACTOR's animation back and forth
(frame! foo 3)
(next-frame! foo)
(start-frame! foo 2)        ; loop's first frame
(end-frame! foo 4)          ; loop's last frame
(play-range! foo 2 4)

color

(color! foo COLOR-RED)
(color! foo (make-color 1 0 0))
(color! foo (make-color 1 0 0 0.5)) ; with opacity
(color-r! foo 0.5)
(color-g! foo 0.7)
(color-b! foo 0.1)
(color-rgb! foo 1 0 0)
(color-rgb! foo 1 0 0 0.5)  ; with opacity
(opacity! foo 0.2)
(fade-out! foo 3)       ; seconds
(fade-in! foo 2)
(fade-in! foo 1 0.5)    ; opacity other than 1
(list-colors)
(define COLOR-MY-BEAUTIFUL-BLUE (make-color 1.0 0.3 0.45)) ; add a custom color

show / hide

(show! foo)
(hide! foo)
(opacity! foo 0.2)

rotate

(angle! foo 45)
(rotate! foo 10)    ; relative (run several times to see the effect)

transform

(size! foo 0.5)
(position! actor 0.7 0.2)   ; normalized coords (0-1).
                            ; XY = 0 0 = top-lef
                            ; XY = 1 1 = bottom-right
(center! foo)
(move! foo 0.1 -0.2)    ; relative to the current position
(move-x! foo -0.3)
(move-y! foo 250)
(move-up! foo 0.1)
(move-down! foo 0.2)
(move-left! foo 0.3)
(move-right! foo 0.4)
(offset! foo 0.1 0)   ; offset the animation relative to the actor's center
(offset-x! foo -0.1)
(offset-y! foo 0.3)
(flip-h! foo)
(flip-v! foo)

parenting

(define-actor bar "my-animation")
(add-child! foo bar)    ; parent + child
(remove-child! bar)     ; only the child is needed

text

(text! foo "write text on foo")     ; write text on actor
(hide-text! foo)
(show-text! foo)
(text-font! foo "res://fonts/TT2020Base-Regular.ttf")
(text-size! foo 32)
(text-visible-characters! foo 3)
(text-visible-ratio! foo 0.5)       ; ratio of visible characters
(text-color! foo COLOR-YELLOW)
(text-show-bg! foo)
(text-hide-bg! foo)

arrange

(front! foo bar)    ; move foo in front of bar
(behind! foo bar)   ; move foo behind bar

fx

(mask! foo bar)             ; bar is mask
(unmask! foo)
(blend-normal! foo)
(blend-add! foo)
(blend-multiply! foo)
(blend-sub! foo)
(color-invert! foo 1)
(color-to-alpha! foo COLOR-WHITE)
(color-to-alpha! foo COLOR-WHITE 0.5)       ; with similarity tolerance
(color-to-alpha! foo COLOR-WHITE 0.8)       ; 0 disable, 1 full, >1 disappear

tweening

(tween! foo "x" 500.0 1.0)      ; actor, target-value, time linear, default ease
(tween! foo "opacity" 0.0 2.0 TRANS_SINE)          ; custom transition
(tween! foo "y" 300.0 1.0 TRANS_BOUNCE EASE_OUT)   ; full control
(tween! foo "size" 1 4 TRANS-BOUNCE)
(tween! foo "color" COLOR-PURE-RED 4)
(list-transitions)
(list-ease-types)

speech bubbles

(say! my-bubble "say something first..." "...and then something else")
(set! *speech-bubble-showing-time-per-word* 0.1)   ; and say again

groups

(group-add! g foo)      ; add 'foo' to the group 'g'
(group-remove! g foo)
(group-set! g "color" COLOR-RED-PURE)
(group-call g "rotate" 10)
(all)                   ; get all the objects
(any)                   ; get any object
(all g)                 ; get all the objects in G
(any-from g)            ; get any object in G
(map (lambda (n) (offset-x! n (random 1.0))) (all))
; batch create group with 10 actors named `zee-00`, `zee-01`, ..., `zee-09`.
(define-many-actors zee 10 some-anim)
; apply commands on every actor of a list
(for-each-in (all g) (lambda (act)      ; 'act' is the current actor in the group
    (x! act (random 1.0))
    (y! act (random 1.0)))

routines

(define-routine
    my-routine                  ; name of the routine
    5                           ; repeats (INF = -1 = forever)
    0.5                         ; interval between repeats (seconds)
    (lambda (tick)              ; proc - `tick` is a counter of calls
        (displayln tick)))
; in one line
(define-routine my-routine 5 0.5 (lambda (tick) (displayln tick)))
(define-routine my-routine INF 0.5 (lambda (tick) (displayln tick)))
(routine-stop! my-routine)
(list-routines)

schedule

(schedule
    2.0                                             ; delay (seconds)
    (lambda () (displayln "fired once after 2s")))  ; proc
(schedule 2.0 (lambda () (displayln "hello")))                  ; one-shot
(make-timer 1.0 (lambda () (displayln "tick")) #t)                  ; one-shot
(define t (make-timer 1.0 (lambda () (displayln "tick")) #f))       ; repeating
(timer-stop! t)
(timer-start! t)

fx

(fx-mix! 1)                     ; 0-1
(fx-feedback! 0.8)              ; 0-1 (or more for aberrations)
(fx-feedback-offset-x! 0.05)    ; 0±1: negative left, positive right
(fx-feedback-offset-y! -0.05)   ; 0±1: positive up, negative down
(fx-feedback-scale! -0.01)      ; 0±1: 0 original size, positive scale up, negative scale down
(fx-noise! -0.2)                ; 0±1: 0 no noise, positive add, negative subtract
(fx-invert! 1)                  ; anything other than 0 (with feedback flashes a lot!)
(fx-light-paint! 1)
(fx-light-paint-decay! 0.9)
(fx-dark-paint! 1)
(fx-dark-paint-decay! 0.9)

window

(window-fullscreen!)
(window-windowed!)
(window-width)              ; pixels
(window-height)
(window-center-width)
(window-center-height)
(window-size-set! 1920 1080)
(window-title-hide!)
(window-title-show!)
(control-window-show!)
(control-window-hide!)

mouse cursor

(mosue-hide!)
(mosue-show!)
(mosue-toggle!)

editor

(editor-set! "(displayln \"replace text\")")
(editor-append! "(displayln \"add text\")")
(editor-clear!)

tele-animatron

(define-tele another-animatron "192.168.1.14" 56101)   ; create a connection
(tele another-animatron
      (rotate! foo 10))     ; rotate `foo` on remote animatron instance

osc

(osc-send "127.0.0.1" 9000 "/trigger" 1 "foo" 3.2) ; ip port addr args ...

receiving OSC on port 56101

(osc-add-input-command! "/gyroscope" (lambda (x y z)
    (angle! my-actor (* 360 x))
    (size! my-actor y))
(define (bla . args)
   (message (list-ref args 0))  ; get the first element from the list
   )
(osc-add-input-command! "/bla" bla)  ; call `bla` from OSC
(osc-ignore! "/foo")                 ; ignore OSC message /foo
(list-osc-input-commands)             ; already added

midi

Warning
 MIDI standard channels, notes and control numbers start counting from 1. Animatron starts counting from 0, following other programming language standards (namely SuperCollider). 
; capture any CC message and pass the channel, control number and value as arguments to the function.
(midi-add-input-command! "/cc" (lambda (ch num val)
  (log-debug (format #f "/cc: ~A ~A ~A" ch num val))))
; => /cc: 0 8 63

; capture only CC messages on channel 1, passing control number and value to the function.
(midi-add-input-command! "/cc/0" (lambda (num val)
  (log-debug (format #f "/cc/0: ~A ~A" num val))))
; => /cc/0: 8 63

; capture only CC messages from control #9 on channel 1
(midi-add-input-command! "/cc/0/8" (lambda (val)
  (log-debug (format #f "/cc/0/8: ~A" val))))
; => /cc/0/8: 63

; define a custom function
(define (bla . args)
    (message (car args)))

(midi-add-input-command! "/cc/0/8" bla) ; call `bla` when MIDI CC 1 on CH 9 arrives

audio

(update
   (size! foo *audio-volume*))
(with-audio-volume (lambda (vol)     ; use audio volume
    (size! foo vol)
    ; add as many expressions as you need
    ))
(on-audio-volume 0.2 (lambda ()    ; trigger when audio is over 0.2
    (rotate! foo 1)
    ; add as many expressions as you need
    ))

logging

(log-level-set! LOG-DEBUG)   ; set verbosity (FATAL, ERROR, WARNING, INFO, VERBOSE, DEBUG)
(log-info "hello")           ; log-fatal, log-error, log-warn, log-info, log-verbose, log-debug

system

(alert-intrusions?)          ; check if intrusions will block the application with an alert
(alert-intrusions-set! #f)   ; disable blocking alert

utils

(vec x y . z)   ; floats
(veci x y . z)  ; ints
(position->pixels 0.1 0.7)          ; convert normalized position to screen size
(random-range 0 100)                ; min, max
(coin 0.5)                          ; 0 = always #f, 1 = always #t
(load "/path/to/file.scm")          ; load scheme file and evaluate it - this is not an addition
(displayln "hello")                 ; print with a line break
(display-list "one" "two" "three")  ; prints elements in different lines
(filter odd? '(1 2 3 4))            ; => (1 3)
(hash-table-keys my-table)          ; returns the list of keys in the hash-table (dictionary)
(hash-table-has-key? my-table 'my-key)
(hash-table-remove! my-table 'my-key)
(node-find-child parent child)  ; find parent's child by name
(degrees-to-radians 90)
(list-join '(1 2 3) ",")    ; => "1,2,3"
(list-find "my-*")          ; '*' = any number of characters, '?' = any ONE character
(find-defined "COLOR-*")    ; search defined symbols with a wildcard
(string-replace "foo" "oo" "ama")   ; => "fama"
(string-count-char "foo" #\o)       ; => 2
(string-strip-edges " foo ")        ; => "foo"
(string-join '("foo" "bar") ", ")   ; => "foo, bar"
(string-split "foo, bar" #\,)       ; => ("foo" " bar")
(string-path-join "/home/me" "dir") ; => "/home/me/dir"
(choose '(0 1 2 3))         ; choose one of ...
(choosen 10 '(0 1 2 3))     ; choose 10 of ...
(series 10 0 0.1)           ; size, start, step
(range 10 20)               ; min, max
(directory-contents "/your/dir")        ; returns the list
(list-directory-contents "/your/dir")   ; prints the list
(pwd)                       ; print name of current/working directory

scheme basics

(+ 1 2)                             ; use PREFIX notation

; define a variable named MY-VARIABLE and assing a string to it
(define my-variable "value")

; define a function named MY-FUNC with one required ARG and any number of OPTIONAL arguments
(define (my-func arg . optional)
    (display "arg: ")
    (display arg)
    (newline)
    (display "opt: ")
    (display optional))

(my-func "with" "some" "args")      ; call function with 3 args

(lambda () (display "a lambda was called")) ; anonymous function that is called immediately
                                            ; and doesn't have a name (so we can't call it
                                            ; again). You can put lambdas as arguments of
                                            ; other procedures if you want to evaluate
                                            ; something before passing it as an argument

my-variable             ; no parenthesis, returns the variable value
'(0 1 2 3)              ; list - notice leading apostrophe (no tailing one)
'my-symbol              ; symbol - notice the leading apostrophe (no tailing one)
"this is a string"      ; double quotes, can contain spaces
*my-global*             ; global variable
MY-CONSTANT             ; SHOULD NOT be changed
(my-setter! ...)        ; `!` means it changes the state of something
(my-predicate? ...)     ; `?` means it returns a boolean that can be checked against the args