doodle/docs/public/Doodad Scripts.md
Noah Petherbridge d28745f89e Mobile Enemy Doodad Test
* Add a Red Azulian as a test for mobile enemies.
  * Its A.I. has it walk back and forth, changing directions when it
    comes up against an obstacle for a few moments.
  * It plays walking animations and can trigger collision events with
    other Doodads, such as the Electric Door and Trapdoor.
* Move Gravity responsibility to the doodad scripts themselves.
  * Call `Self.SetGravity(true)` to opt the Doodad in to gravity.
  * The canvas.Loop() adds gravity to any doodad that has it enabled.
2019-05-06 16:30:45 -07:00

190 lines
5.3 KiB
Markdown

# Doodad Scripts
Each Doodad can have a JavaScript file attached to give them some logic and code
to run in-game when a level is being played. Buttons, trap doors, and other
dynamic doodads have JavaScript code that tells them how to behave.
This game uses [otto](https://github.com/robertkrimen/otto) for its JavaScript
engine, so it only works with ES5 syntax and has a few weird quirks. You get
used to them.
## Example
Provide a script file with a `main` function:
```javascript
function main() {
console.log("%s initialized!", Self.Doodad.Title);
var timer = 0;
Events.OnCollide( function() {
if (timer > 0) {
clearTimeout(timer);
}
Self.ShowLayer(1);
timer = setTimeout(function() {
Self.ShowLayer(0);
timer = 0;
}, 200);
})
}
```
# JavaScript API
# Functions
Global functions available to your script:
## RGBA(uint8 red, uint8 green, uint8 blue, uint8 alpha)
Get a render.Color object from the given color code. Each number
must be between 0 and 255. For example, RGBA(255, 0, 255, 255)
creates an opaque magenta color equivalent to #FF00FF.
The render.Color type may be needed in certain API calls that
require the game's native color type.
## Point(x int, y int)
Get a render.Point object that refers to a position in the game
world.
## Common JavaScript Functions
The following common JavaScript APIs seen in web browsers work
in the doodad scripts:
* int setTimeout(function, int milliseconds)
Set a timeout to run your function after a delay in
milliseconds. Returns a timer ID to be used with
clearTimeout() if you want to cancel the timeout.
* int setInterval(function, int milliseconds)
Like setTimeout, but repeatedly re-runs the function after
the delay in milliseconds. Returns a timer ID to be used
with clearInterval() if you want to cancel the interval.
* clearTimeout(int timerID), clearInterval(int timerID)
Cancel a timeout or interval by passing its timer ID, which
was returned when the timer or interval was first created.
* console.log(str message, v...)
Write to the game's log console. There are also `console.warn`,
`console.error` and `console.log` variants.
## Self
The global variable `Self` holds an API for the current doodad. The full
surface area of this API is subject to change, but some useful examples you
can do with this are as follows.
### Self.Doodad
Self.Doodad is a pointer into the doodad's metadata file. Not
all properties in there can be written to or read from the
JavaScript engine, but some useful attributes are:
* `str Self.Doodad.Title`: the title of the doodad.
* `str Self.Doodad.Author`: the author name of the doodad.
* `str Self.Doodad.Script`: your own source code. Note that
editing this won't have any effect in-game, as your doodad's
source has already been loaded into the interpreter.
* `str Self.Doodad.GameVersion`: the game version that created
the doodad.
### Self.ShowLayer(int index)
Set the doodad's visible layer to the index.
A layer is a drawing created in the in-game format. Only one layer
is visible on-screen during Edit Mode or Play Mode. Layers can be
used to store alternate versions of your doodad to show different
states or as animation frames.
The first and default layer is always zero. Use `CountLayers()`
to query how many layers are in the doodad.
### int Self.CountLayers()
Returns the number of layers, or frames, available in your doodad's
drawing data. Usually these layers are for alternate drawings or animation frames.
The number is the `len()` of the array, and layers are
zero-indexed, so the first and default layer is always layer 0
and the final layer is like so:
```javascript
// set the final frame as the active one
Self.ShowLayer( Self.CountLayers() - 1 );
```
## Animations
### Self.AddAnimation(string name, int interval, [layers...]) error
Add a new animation using some of the layers in your doodad's drawing.
The interval is counted in milliseconds, with 1000 meaning one second between
frames of the animation.
The layers are an array of strings or integers. If strings, use the layer names
from the drawing. With integers, these are the layer index numbers where 0 is
the first (default) layer.
### Self.PlayAnimation(string name, function callback)
Play the named animation. When the animation is finished, the callback function
will be called. Set the callback to `null` if you don't want a callback function.
### Self.StopAnimation()
Stop and cancel any current animations. Their callback functions will not be
called.
### Self.IsAnimating() bool
Returns `true` if an animation is currently playing.
## Events
Use the Events object to register event handlers from your
doodad. Usually you'll configure these in your main() function.
Example configuring event handlers:
```javascript
function main() {
Events.OnCollide(function(e) {
console.log("I've been collided with!");
})
}
```
### OnCollide
Triggers when another doodad has collided with your doodad's box
space on the level. Arguments TBD.
### OnEnter
Triggers when another doodad has fully intersected your doodad's
box.
### OnLeave
Triggers when a doodad who was intersecting your box has left
your box.
### KeypressEvent
Triggers when the player character has pressed a key.
This only triggers when your doodad is the focus of the camera
in-game, i.e. for the player character doodad.