SPX APIs

[nighca]

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

[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

[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