For issue #465, #499

Current supported

`spx.Sprite`

`SetDying`

Mark sprite dying (visible but can't be touched).

SetDying()

`Parent`

Get the game instance.

Parent() *Game

`InitFrom`

Init current sprite from given sprite.

InitFrom(src *Sprite)

`Clone`

Make a clone of current sprite, with optional data (for OnCloned callback).

Clone(data?: any)

`OnCloned`

Listen to current sprite cloned.

OnCloned(callback: func(data?: any))

`OnTouched`

Listen to current sprite touched by another sprite, specified with optional sprite name(s).

OnTouched(callback: func(sprite?: *Sprite))
OnTouched(spriteName: string, callback: func(sprite?: *Sprite))
OnTouched(spriteNames: []string, callback: func(sprite?: *Sprite))

`OnMoving`

Listen to current sprite moving (position change)

OnMoving(callback: func(mi?: *MovingInfo))

`OnTurning`

Listen to current sprite turning (direction change)

OnTurning(callback: func(ti?: *TurningInfo))

`Die`

Let sprite die, with animation die (if defined). SetDying will be called before animation. If current sprite is cloned, it will be destroyed; If not cloned, it will be hided.

Die()

`Destroy`

If current sprite is cloned, it will be fully deleted. Nothing happens if it is not cloned.

Destroy()

`Hide`

Make sprite invisible.

Hide()

`Show`

Make sprite visible.

Show()

`Visible`

Check if sprite visible.

Visible(): bool

`IsCloned`

Check if sprite is cloned.

IsCloned(): bool

`CostumeName`

Get current costume's name.

CostumeName(): string

`CostumeIndex`

Get current costume's index.

CostumeIndex(): int

`SetCostume`

Set current costume.

SetCostume(name: string)
SetCostume(index: int | float64)
SetCostume(action: switchAction) // `switchAction`: `Prev` / `Next`

`NextCostume`

Use next costume as current costume.

NextCostume()

`PrevCostume`

Use previous costume as current costume.

PrevCostume()

`Animate`

Play animation with given name.

Animate(name: string)

`Say`

Show message bubble with given message. Optional seconds can be provided.

Say(msg: any, seconds?: float64)  // non-string `msg` value will be converted with `fmt.Sprint`

`Think`

Show thinking bubble with given message. Optional seconds can be provided.

Think(msg: any, seconds?: float64) // non-string `msg` value will be converted with `fmt.Sprint`

`Quote`

TODO

Quote(msg: string, description?: string, seconds?: float64)

`DistanceTo`

Get distance to target

DistanceTo(target: Target): float64

`Move`

Move given steps, toward current direction, with no animation

Move(step: int | float64)

`Step`

Move given steps, toward current direction, with animation supported

Step(step: int | float64)
Step(step: float64, animationName: string)

`Goto`

Move to given target, with no animation

Goto(target: Target)

`Glide`

Move to given (x,y) position or target, with glide animation

Glide(x, y: float64, seconds: float64)
Glide(target: Target, seconds: float64)

`SetXYpos`

Move to given (x,y) position, with no animation

SetXYpos(x, y: float64)

`ChangeXYpos`

Move with given (x,y) position change, with no animation

ChangeXYpos(dx, dy: float64)

`Xpos`

Get current x position.

Xpos(): float64

`SetXpos`

Move to given x position, with no animation

SetXpos(x: float64)

`ChangeXpos`

Move with given x position change, with no animation

ChangeXpos(dx: float64)

`Ypos`

Get current y position.

Ypos(): float64

`SetYpos`

Move to given y position, with no animation

SetYpos(y: float64)

`ChangeYpos`

Move with given y position change, with no animation

ChangeYpos(dy: float64)

`SetRotationStyle`

Set rotationStyle

SetRotationStyle(style: RotationStyle)

`Heading`

Get current direction.

Heading(): float64

`Turn`

Adjust direction, with animation turn (if defined)

Turn(degree: int | float64) // constants `Right`, `Left`, `Up`, `Down` are supported

`TurnTo`

Turn direction to given value or target, with animation turn (if defined)

TurnTo(direction: int | float64) // constants `Right`, `Left`, `Up`, `Down` are supported
TurnTo(target: Target)

`SetHeading`

Set direction to given value, with no animation

SetHeading(direction: float64)

`ChangeHeading`

Change direction with given direction change, with no animation

ChangeHeading(delta: float64)

`Size`

Get sprite size.

Size(): float64

`SetSize`

Set sprite size.

SetSize(size: float64)

`ChangeSize`

Change size with given size change.

ChangeSize(delta: float64)

`SetEffect`

Set graph effect of given kind with given value. Effects with different kinds may exist at the same time.

SetEffect(kind: EffectKind, value: float64)

`ChangeEffect`

Change graph effect of given kind with given value change (based on existed value of given kind). Effects with different kinds may exist at the same time.

SetEffect(kind: EffectKind, delta: float64)

`ClearGraphEffects`

Clear all graph effects (of all kinds).

ClearGraphEffects()

`TouchingColor`

TODO

TouchingColor(color Color): bool

`Touching`

Check if current sprite touching specified touching target.

Touching(target: TouchingTarget): bool

Note that touching target (TouchingTarget) is different with target, it includes:

sprite name (string)
sprite instance (Sprite)
special object (specialObj): Mouse / Edge / EdgeLeft / EdgeTop / EdgeRight / EdgeBottom

`BounceOffEdge`

Check & bounce off if touching edge

BounceOffEdge()

`GoBackLayers`

Send current sprite backward by specified layer number. Negative layer number results in bringing sprite forward.

GoBackLayers(n: int)

`GotoFront`

Bring current sprite to front.

GotoFront()

`GotoBack`

Send current sprite to back.

GotoBack()

`Stamp`

`PenUp`

`PenDown`

`SetPenColor`

`ChangePenColor`

`SetPenShade`

`ChangePenShade`

`SetPenHue`

`ChangePenHue`

`SetPenHue`

`SetPenSize`

`ChangePenSize`

`SetPenHue`

`HideVar`

Hide stage-monitor which targets current sprite & matches given variable name.

HideVar(variableName: string)

`ShowVar`

Show stage-monitor which targets current sprite & matches given variable name.

ShowVar(variableName: string)

`CostumeWidth`

Get width of sprite current costume.

CostumeWidth(): float64

`CostumeHeight`

Get height of sprite current costume.

CostumeHeight(): float64

`Bounds`

Get bounding rectangle of current sprite.

Bounds(): *math32.RotatedRect

`spx.Game`

`IsRunned`

Check if game is already running.

IsRunned(): bool

`Run`

Run the game.

Run(resource interface{}, gameConf ...*Config) // `resource` can be a `string` or `fs.Dir` object.

`MouseHitItem`

MouseHitItem returns the topmost sprite which is hit by mouse.

MouseHitItem() (target *Sprite, ok bool)

`Reload`

Reload the game.

Reload() (err error)
Reload(configFile: io.Reader) (err error)
Reload(configFilePath: string) (err error)

`Layout`

Get window size.

Layout(outsideWidth, outsideHeight int): (windowWidth, windowHeight int) // `outsideWidth`, `outsideHeight` is not actually used

`Update`

Do game update.

Update(): error

`Draw`

`EraseAll`

`SceneName`

Get name of current scene.

SceneName() string

`SceneIndex`

Get index of current scene.

SceneIndex() int

`StartScene`

Switch to given scene. It can be blocking or non-blocking by specifying optional wait. Non-blocking by default.

StartScene(name: string, wait?: bool)
StartScene(index: int | float64, wait?: bool)
StartScene(action: switchAction, wait?: bool) // `switchAction`: `Prev` / `Next`

`NextScene`

Switch to next scene. It can be blocking or non-blocking by specifying optional wait. Non-blocking by default.

NextScene(wait?: bool)

`PrevScene`

Switch to previous scene. It can be blocking or non-blocking by specifying optional wait. Non-blocking by default.

PrevScene(wait?: bool)

`KeyPressed`

Check if given key is now pressed.

KeyPressed(key Key) bool

`MouseX`

Get current x position of mouse.

MouseX() float64

`MouseY`

Get current y position of mouse.

MouseY() float64

`MousePressed`

Check if mouse is now pressed.

MousePressed() bool

`Username`

`Wait`

Block current execution (coroutine) for given seconds.

Wait(seconds: float64)

`Timer`

`ResetTimer`

`Ask`

`Answer`

`SetEffect`

`ChangeEffect`

`ClearSoundEffects`

`Play`

Play given sound. By specifing extra options we can control more detailed playing behavior.

Play(sound: Sound, wait?: bool)
Play(sound: Sound, options?: PlayOptions)
Play(soundName: string, wait?: bool)
Play(soundName: string, options?: PlayOptions)

type PlayOptions struct {
	Action PlayAction
	Wait   bool
	Loop   bool
}

`StopAllSounds`

Stop all playing sounds.

StopAllSounds()

`Volume`

Get current volume for sounds.

Volume(): float64

`SetVolume`

Set current volume for sounds.

SetVolume(volume float64)

`ChangeVolume`

Change current volume for sounds with given volume change.

ChangeVolume(delta float64)

`Loudness`

Get current device volume for audio recording.

Loudness(): float64

`Broadcast`

Broadcast given message with optional given data. It can be blocking or non-blocking by specifying optional wait. Non-blocking by default.

Broadcaset(msg string, wait?: bool)
Broadcaset(msg string, data: any, wait: bool)

`HideVar`

Hide stage-monitor which targets the stage & matches given variable name.

HideVar(variableName: string)

`ShowVar`

Show stage-monitor which targets the stage & matches given variable name.

ShowVar(variableName: string)

`spx.eventSink`

`OnStart`

Listen to game start.

OnStart(onStart func())

`OnClick`

Listen to current target (sprite / stage) clicked.

OnClick(onClick func())

`OnAnyKey`

Listen to any key pressed.

OnAnyKey(callback func(key Key))

`OnKey`

Listen to given key(s) pressed.

OnKey(key: Key, callback: func())
OnKey(keys: []Key, callback: func())
OnKey(keys: []Key, callback: func(Key))

`OnMsg`

Listen to message broadcasted.

OnMsg(callback: func(msg: string, data: any))
OnMsg(msg: string, callback: func())

`OnScene`

Listen to scene switching.

OnScene(callback: func(name: string))
OnScene(name: string, callback: func())

`Stop`

Stop specified script(s)'s execution.

Stop(kind StopKind)

Global

`Rand`

Get random number.

Rand(from, to int): float64
Rand(from, to float64): float64

`Iround`

Return the nearest interger to given number.

Iround(v float64) int

`RGB`

Define color with R, G, B

RGB(r, g, b uint8) Color

`RGBA`

Define color with R, G, B, A

RGB(r, g, b, a uint8) Color

`Exit`

Exit game.

Exit(code?: int)

`SchedNow`

`Sched`

`SetDebug`

`switchAction`

Action for costume / scene switch

Prev, Next

`specialDir`

Heading direction / degree.

Right, Left, Up, Down

`specialObj`

Targets for operations like Goto, DistanceTo, ...

Mouse
Edge
EdgeLeft
EdgeTop
EdgeRight
EdgeBottom

`EffectKind`

Graph effect kind for sprites.

ColorEffect, BrightnessEffect, GhostEffect

`Key`

Keys on keyboard.

Key0-KeyAny

`PlayAction`

Actions for sound playing.

PlayRewind, PlayContinue, PlayPause, PlayResume, PlayStop

`Pos`

Special positions for operations like Goto.

Invalid
Last
All
Random

`RotationStyle`

None, Normal, LeftRight

`StopKind`

All / _All: stop all scripts of stage/sprites and abort this script
AllOtherScripts: stop all other scripts
AllSprites: stop all scripts of sprites
ThisSprite: stop all scripts of this sprite
ThisScript: abort this script
OtherScriptsInSprite: stop other scripts of this sprite

Extra definitions

`Target`

Define target: Target as a target with position (sprite, mouse, ...), it may be

sprite name (string)
sprite instance (Sprite)
special object (specialObj), while spx.Mouse only
position (Pos), while spx.Random only

May 10 '24 07:05 nighca

v1.3 不暴露如下概念：

graphic-effect: effect 控制相关不暴露
stage-monitor: ShowVar / HideVar 等不暴露
animation: animation 相关不暴露，另外包括像 Step、Turn 这种有几乎等价的方法（Move、SetHeading），区别只是自己带有动画的方法
draw: draw 相关不暴露，另外 RGB/RGBA 等为 draw 操作服务的方法也不暴露
value & list

另外考虑 backdrop 命名调整，详见 #456

May 11 '24 08:05 nighca

Expected to expose in v1.3

TODO: backdrop 相关需要调整命名

`spx.Sprite`

~~Parent~~
Clone
OnCloned
OnTouched
OnMoving
OnTurning
Die
Hide
Show
Visible
CostumeName
CostumeIndex
SetCostume
NextCostume
PrevCostume
Say
Think
DistanceTo
Move
Goto
Glide
SetXYpos
ChangeXYpos
Xpos
SetXpos
ChangeXpos
Ypos
SetYpos
ChangeYpos
Heading
TurnTo
SetHeading
ChangeHeading
Size
SetSize
ChangeSize
Touching
BounceOffEdge
~~Bounds~~

`spx.Game`

MouseHitItem
SceneName
SceneIndex
StartScene
NextScene
PrevScene
KeyPressed
MouseX
MouseY
MousePressed
Wait
Play
StopAllSounds
Volume
SetVolume
ChangeVolume
Broadcast

`spx.eventSink`

OnStart
OnClick
OnAnyKey
OnKey
OnMsg
OnScene

Global

Rand
Exit
switchAction: Prev, Next
specialDir: Right, Left, Up, Down
specialObj: Mouse, Edge, EdgeLeft, EdgeTop, EdgeRight, EdgeBottom
Key: Key0-KeyAny
PlayAction: PlayRewind, PlayContinue, PlayPause, PlayResume, PlayStop
Pos: Invalid, Last, All, Random

May 11 '24 09:05 nighca

SPX APIs

Current supported

spx.Sprite

SetDying

Parent

InitFrom

Clone

OnCloned

OnTouched

OnMoving

OnTurning

Die

Destroy

Hide

Show

Visible

IsCloned

CostumeName

CostumeIndex

SetCostume

NextCostume

PrevCostume

Animate

Say

Think

Quote

DistanceTo

Move

Step

Goto

Glide

SetXYpos

ChangeXYpos

Xpos

SetXpos

ChangeXpos

Ypos

SetYpos

ChangeYpos

SetRotationStyle

Heading

Turn

TurnTo

SetHeading

ChangeHeading

Size

SetSize

ChangeSize

SetEffect

ChangeEffect

ClearGraphEffects

TouchingColor

Touching

BounceOffEdge

GoBackLayers

GotoFront

GotoBack

Stamp

PenUp

PenDown

SetPenColor

ChangePenColor

SetPenShade

ChangePenShade

SetPenHue

ChangePenHue

SetPenHue

SetPenSize

ChangePenSize

SetPenHue

HideVar

ShowVar

CostumeWidth

CostumeHeight

Bounds

spx.Game

IsRunned

Run

MouseHitItem

Reload

`spx.Sprite`

`SetDying`

`Parent`

`InitFrom`

`Clone`

`OnCloned`

`OnTouched`

`OnMoving`

`OnTurning`

`Die`

`Destroy`

`Hide`

`Show`

`Visible`

`IsCloned`

`CostumeName`

`CostumeIndex`

`SetCostume`

`NextCostume`

`PrevCostume`

`Animate`

`Say`

`Think`

`Quote`

`DistanceTo`

`Move`

`Step`

`Goto`

`Glide`

`SetXYpos`

`ChangeXYpos`

`Xpos`

`SetXpos`

`ChangeXpos`

`Ypos`

`SetYpos`

`ChangeYpos`

`SetRotationStyle`

`Heading`

`Turn`

`TurnTo`

`SetHeading`

`ChangeHeading`

`Size`

`SetSize`

`ChangeSize`

`SetEffect`

`ChangeEffect`

`ClearGraphEffects`

`TouchingColor`

`Touching`

`BounceOffEdge`

`GoBackLayers`

`GotoFront`

`GotoBack`

`Stamp`

`PenUp`

`PenDown`

`SetPenColor`

`ChangePenColor`

`SetPenShade`

`ChangePenShade`

`SetPenHue`

`ChangePenHue`

`SetPenHue`

`SetPenSize`

`ChangePenSize`

`SetPenHue`

`HideVar`

`ShowVar`

`CostumeWidth`

`CostumeHeight`

`Bounds`

`spx.Game`

`IsRunned`

`Run`

`MouseHitItem`

`Reload`

`Layout`

`Update`