Reading the PulpScript Docs

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 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.