guidebook/docs/custom-doodads/scripts.md

88 lines
3.2 KiB
Markdown
Raw Normal View History

2020-11-21 03:09:16 +00:00
# Doodad Scripts
2021-09-04 05:49:59 +00:00
Doodads are programmed using (ES5) JavaScript which gives them their behavior
2021-10-09 01:35:52 +00:00
and ability to interact with the player and other doodads. Doodad scripts are
run during "Play Mode" when a level _containing_ the doodad is being played.
2020-11-21 03:09:16 +00:00
2021-10-09 01:35:52 +00:00
The main() function of your script is called to initialize your doodad. Here
is an example what a doodad script may look like:
2020-11-21 03:09:16 +00:00
```javascript
function main() {
// Logs go to the game's log file (standard output on Linux/Mac).
console.log("%s initialized!", Self.Title);
2021-10-09 01:35:52 +00:00
// NOTE: you can configure the hitbox in the editor, this function
// can define it in script. This box marks the region you want to
// be 'solid' or whatever, the hot spot of your doodad.
2020-11-21 03:09:16 +00:00
Self.SetHitbox(0, 0, 64, 12);
// Handle a collision when another doodad (or player) has entered
2021-10-09 01:35:52 +00:00
// the space of our doodad. The `e` has info about the event.
2024-05-05 02:33:07 +00:00
Events.OnCollide((e) => {
2020-11-21 03:09:16 +00:00
console.log("Actor %s has entered our hitbox!", e.Actor.ID());
// InHitbox is `true` if we defined a hitbox for ourselves, and
// the colliding actor is inside of the hitbox we defined.
2021-10-09 01:35:52 +00:00
// To prohibit movement, return false from the OnCollide handler.
// If you don't return false, the actor is allowed to keep on
// moving through.
2020-11-21 03:09:16 +00:00
if (e.InHitbox) {
return false;
}
// When movement is finalized, OnCollide is called one final time
// with e.Settled=true; it is only then that a doodad should run
// event handlers for a logical collide event.
if (e.Settled) {
// do something
Message.Publish("power", true);
}
});
2021-10-09 01:35:52 +00:00
// Subscribe to "broadcast:ready" and don't publish messages
// until the game is ready!
2024-05-05 02:33:07 +00:00
Message.Subscribe("broadcast:ready", () => {
2021-10-09 01:35:52 +00:00
// It is now safe to publish messages to linked doodads, something that
// could have deadlocked otherwise!
Message.Publish("ping", null);
})
2020-11-21 03:09:16 +00:00
// OnLeave is called when an actor, who was previously colliding with
// us, is no longer doing so.
2024-05-05 02:33:07 +00:00
Events.OnLeave((e) => {
2020-11-21 03:09:16 +00:00
console.log("Actor %s has stopped colliding!", e.Actor.ID());
})
}
```
2021-09-04 05:49:59 +00:00
## Installing a Doodad Script
2020-11-21 03:09:16 +00:00
2021-09-04 05:49:59 +00:00
Scripts can be attached to your doodad either in-game (using the Doodad
Properties window in the editor) or by using the command-line `doodad` program.
![In-game Script UI](../images/doodad-properties.png)
Using the command-line [`doodad` tool](../doodad-tool.md):
2020-11-21 03:09:16 +00:00
```bash
# Attach the JavaScript at "script.js" to the doodad file "filename.doodad"
doodad install-script script.js filename.doodad
# To view the script currently attached to a doodad
# (prints the script to your terminal)
doodad show --script filename.doodad
```
2021-09-04 05:49:59 +00:00
## Testing Your Script
2020-11-21 03:09:16 +00:00
The best way to test your doodad script is to use it in a level!
Run the game in a console to watch the log output, and you can use functions
like `console.log()` in your script to help debug issues. Drag your custom
doodad into a level and playtest it! Your script's main() function is called
when the level instance of your doodad is initialized.
2021-09-04 05:49:59 +00:00
## JavaScript API
2020-11-21 03:09:16 +00:00
2024-05-05 02:33:07 +00:00
Please see the [Script API Reference](api-reference.md) for full details.