Reading the PulpScript Docs
Tags: gamedev, beginners, playdate, pulp
Published: 2023-01-21 02:02:24

## Previously on...
In the last article I learned a ton about Pulp and all the wonderful ways it makes developing simple games for the Playdate real easy.

Even for simple games, though, it's tough to make a fun game without a little programming.

That's where PulpScript comes in.

Thus far, I've studied a few games' script files.

Many were easy to interpret.

But there were commands I didn't fully understand.

I hope that reading the official [PulpScript Docs](https://play.date/pulp/docs/pulpscript) fills in all those gaps...and sheds plenty more light on what I can do with this handy API.

## Table of Contents
- Woah! This document is nearly three times as long as the Pulp Docs!
- Looks like there is a section on the aspects of the language, then several sections all about the many functions made available by the API

## General
This language has:
- Variables
- Event Handlers
- Persistant Storage
- Math
- Control Flow
- Comments
- Strings
- Loops
- Dates and Times

I've dabbled in all of that!

### Interesting excerpts
> All game logic must occur inside an event handler.

> All variables are globally scoped.

> All uninitialized variables have a default value of `0`.

> Variables can hold a number or a string. Strings must be wrapped in double quotes.

> Compound expressions are not supported.

Oh, that explains why I kept seeing overly nested `if...then` clauses in all the games: because there's not logical AND or OR in PulpScript!

> String comparisons are case-sensitive.

> Callbacks and event handlers can be exited early with the done statement

> Variables can be persisted across launches using the `store` and `restore` functions.

Oh, so that's what those keywords were doing!

- `call` triggers an event for the current tile
- `emit` triggers an event for all tiles that implement that particular event
- No `for` loops, but there is a `while` loop

### Functions
The built-in functions I recall:
- `load`
- `finish`
- `loop`
- `update`
- `confirm`
- `cancel`
- `crank`
- `draw`
- `interact`
- `collect`

When these functions are called:
- on the game, or once on the game
- on each room, or the current room
- on each tile or the current tile
- on the Player each time they move or collide with a tile
- on an item when the player collides with that tile

The menu-related functions:
- `change`
- `select`
- `dismiss`
- `invalid`

I wonder how the cursor is controlled in a Pulp game...especially such that a series of menu items in-game can be selected using any of the buttons on the Playdate.

The functions I now know exist:
- `start`, `enter`, `exit`
- `bump`
- `dock`, `undock`
- `any`
- `mimic`

### The `event` object
Throughout the built-in functions, the `event` object may have one or more of the following read-only `members` a.k.a. properties:
- `dx` - horizontal direction: -1 (up), 0 (same), 1 (down)
- `dy` - vertical direction: -1 (up), 0 (same), 1 (down)
- `tx` - X coordinate of the target tile relative to the room
- `ty` - Y coordinate of the target tile relative to the room
- `x` - X coordinate of the tile
- `y` - Y coordinate of the tile
- `tile` - name of the current tile
- `room` - name of the current room
- `px` - current player X coordinate
- `py` - current player Y coordinate
- `aa` - absolute angle of the crank
- `ra` - relative angle of the crank (degree difference relative to the previous frame)
- `frame` - number of frames elapsed since game start
- `ax` - accelerometer's X value
- `ay` - accelerometer's Y value
- `az` - accelerometer's Z value
- `orientation` - a string describing the Playdate's current orientation
- `option` - currently selected option's name
- `game` - name of the game
- `player` - name of the player tile

### The `config` object
This object can be used to override the default settings through its writable members.

Things that can be changed include:
- Input delays
- Camera settings
- Color of out-of-bounds tiles
- Time delays
- Text interaction and display timings

### The `datetime` object
Lots of great variables for use in tracking time!

### String formatting
Hooray for use of curly braces to interpolate values inside a string!

And very cool that strings can be padded on each side a specific amount.

And putting tiles in a string? Hmm. I'm not sure how I would use that, but cool.

## Functions again!
- `log` works as expected
- `dump` is a great troubleshooting tactic
- `say` presents a message...and can be positioned and re-sized!
- `ask` is like a `switch` statement where each clause is an `option` and the body of a reaction
- I wonder how `menu` differs in appearance and use than `ask`
- `fin` is the true game-ending prompt, eh? At least because it emits the `on finish do` event
- `swap` replaces a tile's artwork with that of another
- `frame` and `frameIndex` capture a frame from a tile's animation set
- `play` starts - optionally interrupting? - a tile's series of animation frames
- `wait` creates a delay, with exception to the `run` loop...? And there's a caveat about preventing player movement? I don't quite understand those parts yet.
- `shake` is a nice touch!
- `tell` lets me manipulate one tile from another
- `call` and `emit` do the same thing, but one for a single tile and the other for any/all applicable tiles
- `mimic` seems interesting, but not sure what a use case is at this moment
- `ignore` and `listen` are great player-input-disabling functions!
- `act` is very interesting: perform some foreshadowing!
- `draw` can only be called from the Player's `draw` event...interesting.
- `hide` makes it impossible to draw the player. So...like, to simulate a tunnel?
- `window` draws a window frame. Cool?
- `label` places text on the room and not in a window or prompt: so for UI elements, perhaps?
- `fill` draws rectangles!
- `crop` essentially creates a mask over the room within which drawing can occur
- `goto` moves the player to a position in a room
- `sound` plays a sound
- `once` plays a song and stops, optionally doing more things when the song has finished
- `loop` plays a song again and again
- `stop` ends the currently playing song
- `btm` adjusts the beat of the song
- `store` sets a value in storage when a game or room is entered or exited
- `restore` sets a value from one in storage
- `toss` deletes values from storage
- `random` generates a random integer
- `floor` rounds a decimal down to the nearest integer
- `ceil` rounds a decimal up to the nearest integer
- `round` rounds a decimal to the closest integer
- `sine`, `cosine`, `tangent` do geometry things based on a number
- `radians` converts a number from degrees to radians
- `degrees` converts a number from radians to degrees
- `invert` draws the opposite color and returns the current mode
- `solid` identifies a tile as solid or not
- `type` identifies a tile's type
- `id` identifies a tile from its position or name
- `name` identifies a tile from its position or id

## Lots of feelings
- So many event functions!
- So many event object members!
- So many other functions!
- Tons of knowledge gaps filled!
- Lots of questions about some of these functions and event handlers!
- Excitement to `log` tons of things in tons of event handlers to learn first-hand how all this works!

## What next?
- Try to find a comprehensive tutorial on building a game in Pulp?
- Start with the list of links on the Pulp help page?
- Or see what's on Youtube?
- Or skip all that and just play around in the editor myself, struggling gleefully the whole time?

It all sounds like it's gonna be a ton of fun...especially now that I'm more familiar with PulpScript and how Tiles work.