Module perentie

The Perentie scripting API.

General

Get the version string of the Perentie engine.
Get the platform which Perentie is running on.
Set the current game.
Print a message to the Perentie log.
Print an error message to the Perentie log.
Get the number of milliseconds elapsed since the engine started.
Get the dimensions of the screen in pixels.
Quit Perentie.
Reset Perentie.
Return the game's variable store.

Save/Load

Return the file name for a saved state.
Reset Perentie and load the engine state from a file.
Get the path for writing app-specific data.
Save the current game state to a file.
Export the current game state.
Import game state from a payload.
Get a summary of a single save state file.
Fetch summaries for all available save state files.

Math

Calculate the angle of a 2D direction vector.
Calculate the delta angle between two directions.
Calculate a direction angle mirrored by a plane.
Return a unique 32-bit hash for a string.
Generate 1D Perlin simplex noise.
Generate 2D Perlin simplex noise.
Generate 3D Perlin simplex noise.
Generate fractal brownian motion summation of 1D Perlin simplex noise.
Generate fractal brownian motion summation of 2D Perlin simplex noise.
Generate fractal brownian motion summation of 3D Perlin simplex noise.

Callbacks

Event structure
Set a callback for an event.
Set a callback for when the mouse moves over a new PTActor/PTBackground/PTSprite.
Set a callback for before rendering the current frame to the screen.
Set a callback for when the user indicates they wish to skip a single spoken line.
Set a callback for when the user indicates they wish to fast-forward a thread.
Set a callback for setting up a particular room.
Set a callback for unloading a particular room.
Set a callback for switching to a particular room.
Set a callback for switching away from a room.
Set the callback to run when loading a game state.
Set the callback to run when saving a game state.

Input

Get the last recorded mouse position.
Grab the player's input.
Release the player's input.
Return whether the player's input is grabbed.
Return whether the engine has seen a touchscreen input.
Get the current object which the mouse is hovering over

Walk box

Point structure
Create a new point.
Walk box structure.
Create a new walk box.
Set a callback for when an actor enters a walk box.
Generate a list of connections between PTWalkBox objects.
Generate a matrix describing the shortest path between walk boxes.

Actors

Actor structure.
Create a new actor.
Set an actor's walk box.
Set whether to automatically wait after a PTActor starts talking.
Get the base delay for talking.
Get the character delay for talking.
Set the base delay for talking.
Set the chracter delay for talking.
Make an actor talk.
Make an actor stop talking.
Sleep the current thread.
Set an actor moving towards a point in the room.
Add an actor to the engine state.
Remove an actor from the engine state.
Move an actor into a different room.
Set the current animation to play on an actor's sprite.

Rendering

Image structure.
Load a new image.
Load a sequence of images.
9-slice image reference structure.
Create a new 9-slice image reference.
Create a copy of a 9-slice image reference with different dimensions.
Get the dimensions of an image.
Get the origin position of an image.
Set the origin position of an image.
Set the origin position of an image.
Blit a PTImage/PT9Slice to the screen.
Perform a collision test for an image.
Return the current palette.
Set the automatic palette remapper to use.
Set whether to clear the screen at the start of every frame
Set the overscan colour.
Set a dithering hint.
Background structure.
Create a new background.
Animation structure.
Create a new animation.
Sprite structure.
Create a new sprite.
Set the current animation to play on a sprite.
Increment a sprite's current animation frame.
Group structure.
Create a new group.
Add a renderable (PTActor/PTBackground/PTSprite/PTGroup) object to a group rendering list.
Remove a renderable (PTActor/PTBackground/PTSprite/PTGroup) object from a group rendering list.
Iterate through a list of renderable (PTActor/PTBackground/PTSprite/PTGroup) objects.
Fetch the image to use when rendering a PTActor/PTBackground/PTSprite object.
Add a renderable (PTActor/PTBackground/PTSprite/PTGroup) object to the global rendering list.
Remove a renderable (PTActor/PTBackground/PTSprite/PTGroup) object from the global rendering list.

Movement

Return a function for linear interpolation.
Return a function for a unit cubic bezier curve.
Return a preset timing function.
Movement reference structure.
Create a new movement reference.
Move an object smoothly to a destination point.
Move an object smoothly to a destination point relative to the object's current position.
Check if an object is moving.
Return a function for shaking using simplex noise.
Shake reference structure
Create a new shake reference.
Shake an object without changing its position.

GUI controls

Panel structure
Create a new panel.
Horizontal slider structure.
Create a new horizontal slider control.
Convert a slider position to a value.
Convert a slider value to a position.
Set a slider to a value.
Button structure.
Create a new button control.
Remove a panel from the engine state.
Add a renderable (PTBackground/PTSprite/PTGroup) object to the panel rendering list.
Remove a renderable (PTBackground/PTSprite/PTGroup) object from the panel rendering list.

Text

Bitmap font structure.
Create a new bitmap font.
Create an new image containing rendered text.

Audio

Wave structure
Load a new wave file.
Convert a tone frequency to a position on the MIDI pitch scale.
Convert a MIDI pitch to a tone frequency.
Convert a tone frequency to an Inverse Frequency Sound value.
PC speaker data structure.
Create a new PC speaker data buffer.
Create a new PC speaker data buffer, using tone frequency values.
Play a square wave tone on the PC speaker.
Play an audio sample through the PC speaker.
Play a data buffer through the PC speaker.
Stop all playback through the PC speaker.
Load a PC speaker sound file in Inverse Frequency Sound format.
Load a music file in Reality Adlib Tracker format.
Start playing the music loaded in the RAD player.
Stop playing the music loaded in the RAD player.
Get the path of the currently playing file in the RAD player.
Get the master volume of the RAD player.
Set the master volume of the RAD player.
Get the playback head position of the RAD player.
Set the playback head position of the RAD player.
Start playing the music loaded in the RAD player with a volume fade-in.
Stop playing the music loaded in the RAD player with a volume fade-out.

Threading

Start a function in a new thread.
Stop a running thread.
Fast forward the current thread.
Fast forward the named thread.
Perform a talk skip on the current thread.
Perform a talk skip on the named thread.
Check whether a thread is in the fast forward state.
Check whether a thread is running.
Sleep the current thread.
Sleep the current thread until an actor finishes the action in progress.
Sleep the current thread until an object finishes moving.
Sleep the current thread until a PTAnimation reaches the end.
Toggle the use of the watchdog to abort threads that take too long.
Set the number of Lua instructions that need to elapse without a sleep before the watchdog aborts a thread.
Assert that this function can't be run more than once.

Rooms

Room structure.
Create a new room.
Add a renderable (PTActor/PTBackground/PTSprite/PTGroup) object to the room rendering list.
Remove a renderable (PTActor/PTBackground/PTSprite/PTGroup) object from the room rendering list.
Update the depth ordering of the objects in the room.
Set the walk boxes for a room.
Find the next walk box in the shortest path to reach a target walk box.
Convert coordinates in screen space to room space.
Convert coordinates in room space to screen space.
Return the current room.
Return a room by name.
Add a room to the engine state.
Remove a room from the engine state.
Switch the current room.
Sleep the current thread until a room finishes the action in progress.
Set whether to automatically wait after a PTRoom starts talking.
Make the current room talk.
Make the current room stop talking.
Sleep the current thread.

Verbs

Set a callback for a single-subject verb action.
Run a single-subject verb action in the verb thread.
Set a callback for determining if the engine can trigger a verb action.
Set a callback for a two-subject verb action.
Run a two-subject verb action in the verb thread.
Set whether to grab the user input when a verb callback is run.
Return whether the current queued verb action is ready.

Debug

Set whether to draw the walkbox of the current room
Set whether to draw the bounding boxes of images.
Set whether to enable the debug console.


General

PTVersion ()
Get the version string of the Perentie engine.

Returns:

    string Version string.
PTPlatform ()
Get the platform which Perentie is running on.

Returns:

    string Platform string. Options are: "dos", "sdl", "web"
PTSetGameInfo (id, version, name)
Set the current game. Required in order to use the save/load system.

Parameters:

  • id string Identifier code for the game, in reverse domain format. Used to check that a saved state is for the correct game.
  • version string Version number of the code. Used to state which version of the game created a save state.
  • name string Human readable name
PTLog (format, ...)
Print a message to the Perentie log. By default, this is only visible if Perentie is started with the --log option. This is a more accessible replacement for Lua's print function, which will only output to the debug console.

Parameters:

PTLogError (format, ...)
Print an error message to the Perentie log. This will always display.

Parameters:

PTGetMillis ()
Get the number of milliseconds elapsed since the engine started.

Returns:

    integer Number of milliseconds.
PTGetScreenDims ()
Get the dimensions of the screen in pixels.

Returns:

  1. integer Width of the screen.
  2. integer Height of the screen.
PTQuit ([retcode=0])
Quit Perentie.

Parameters:

  • retcode integer Return code. (default 0)
PTReset ()
Reset Perentie. Clears the scripting engine and restarts.
PTVars ()
Return the game's variable store. This will be preserved as part of PTLoadState and PTSaveState. Please use the variable store for simple types only (i.e. strings, numbers, booleans, and tables); you're aiming for the bare minimum of information to describe the current game state. You do not need to store information about the current room and the state of the actors, as these are stored by the engine automatically. You can use a PTOnLoadState or PTOnRoomLoad hook to apply any settings after a game is loaded.

Returns:

    table Table of variables, containing key-value pairs.

Save/Load

PTSaveFileName (index)
Return the file name for a saved state.

Parameters:

  • index integer Index, between 0 and 999.

Returns:

    string The file name.
PTLoadState ([index=nil])
Reset Perentie and load the engine state from a file. Similar to PTReset, this will clear the scripting engine and restart.

Parameters:

  • index integer Save game index to use. This will be stored in the user's app data path, as provided by PTGetAppDataPath. (default nil)
PTGetAppDataPath ()
Get the path for writing app-specific data.

Returns:

    string The app data path (absolute).
PTSaveState (index[, state_name=""])
Save the current game state to a file. This is a deferred operation.

Parameters:

  • index integer Save game index to use. This will be stored in the user's app data path, as provided by PTGetAppDataPath, with the filename provided by PTSaveFileName.
  • state_name string Name of the saved state. Useful for e.g. listing saved games. (default "")
PTExportState (state_name)
Export the current game state.

Parameters:

  • state_name string Name of the saved state. Useful for e.g. listing saved games.

Returns:

    table Engine state information payload. When saving to a file with PTSaveState, this data is encoded as CBOR.
PTImportState (state)
Import game state from a payload. This will overwrite variables in the game's variable store, and update the state of all PTRooms and PTActors.

Parameters:

  • state table Engine state information payload. When loading state from a file with PTLoadState, this data is encoded as CBOR.
PTGetSaveStateSummary (index)
Get a summary of a single save state file.

Parameters:

  • index integer Save game index to use. This will be fetched from the user's app data path, as provided by PTGetAppDataPath, with the filename provided by PTSaveFileName.

Returns:

    table A table containing "index", "name" and "timestamp" keys, or nil if the file wasn't found.
PTListSavedStates ()
Fetch summaries for all available save state files.

Returns:

    table A list of tables containing "index", "name" and "timestamp" keys; one for each available save state file.

Math

PTAngleDirection (dx, dy)
Calculate the angle of a 2D direction vector.

Parameters:

  • dx number Direction vector x coordinate.
  • dy number Vector y coordinate.

Returns:

    integer Direction in degrees clockwise from north.
PTAngleDelta (src, dest)
Calculate the delta angle between two directions.

Parameters:

  • src integer Start direction, in degrees clockwise from north.
  • dest integer End direction, in degrees clockwise from north.

Returns:

    integer Angle between the two directions, in degrees clockwise.
PTAngleMirror (src, plane)
Calculate a direction angle mirrored by a plane.

Parameters:

  • src integer Start direction, in degrees clockwise from north.
  • plane integer Plane direction, in degrees clockwise from north.

Returns:

    integer Reflected direction, in degrees clockwise from north.
PTHash (src)
Return a unique 32-bit hash for a string.

Parameters:

  • src string String to process.

Returns:

    integer 32-bit hash, encoded as an integer.
PTSimplexNoise1D (x)
Generate 1D Perlin simplex noise.

Parameters:

  • x float X coordinate.

Returns:

    float Noise value, [-1, 1]. 0 on all integer coordinates.
PTSimplexNoise2D (x, y)
Generate 2D Perlin simplex noise.

Parameters:

  • x float X coordinate.
  • y float Y coordinate.

Returns:

    float Noise value, [-1, 1]. 0 on all integer coordinates.
PTSimplexNoise3D (x, y, z)
Generate 3D Perlin simplex noise.

Parameters:

  • x float X coordinate.
  • y float Y coordinate.
  • z float Z coordinate.

Returns:

    float Noise value, [-1, 1]. 0 on all integer coordinates.
PTSimplexFractal1D (frequency, amplitude, lacunarity, persistence, octaves, x)
Generate fractal brownian motion summation of 1D Perlin simplex noise.

Parameters:

  • frequency float Frequency of the first octave of noise.
  • amplitude float Amplitude of the first octave of noise.
  • lacunarity float Frequency multiplier between successive octaves.
  • persistence float Loss of amplitude between successive octaves.
  • octaves integer Number of fraction of noise to sum.
  • x float X coordinate.

Returns:

    float Noise value, [-1, 1]. 0 on all integer coordinates.
PTSimplexFractal2D (frequency, amplitude, lacunarity, persistence, octaves, x, y)
Generate fractal brownian motion summation of 2D Perlin simplex noise.

Parameters:

  • frequency float Frequency of the first octave of noise.
  • amplitude float Amplitude of the first octave of noise.
  • lacunarity float Frequency multiplier between successive octaves.
  • persistence float Loss of amplitude between successive octaves.
  • octaves integer Number of fraction of noise to sum.
  • x float X coordinate.
  • y float Y coordinate.

Returns:

    float Noise value, [-1, 1]. 0 on all integer coordinates.
PTSimplexFractal3D (frequency, amplitude, lacunarity, persistence, octaves, x, y, z)
Generate fractal brownian motion summation of 3D Perlin simplex noise.

Parameters:

  • frequency float Frequency of the first octave of noise.
  • amplitude float Amplitude of the first octave of noise.
  • lacunarity float Frequency multiplier between successive octaves.
  • persistence float Loss of amplitude between successive octaves.
  • octaves integer Number of fraction of noise to sum.
  • x float X coordinate.
  • y float Y coordinate.
  • z float Z coordinate.

Returns:

    float Noise value, [-1, 1]. 0 on all integer coordinates.

Callbacks

PTEvent
Event structure

Fields:

  • _type string "PTEvent"
  • type string Event type code. Options are: "null", "start", "quit", "reset", "keyDown", "keyUp", "mouseMove", "mouseDown", "mouseUp"
  • status integer Used by "quit". Exit status code. (default nil)
  • statePath string Used by "reset". Path to the saved state to load. (default nil)
  • key string Used by "keyDown" and "keyUp". Key that has been pressed. (default nil)
  • isRepeat boolean Used by "keyDown". Whether this event is caused by the key repeat rate. (default nil)
  • flags integer Used by "keyDown". Bitmask of modifier keys engaged during the keypress. (default nil)
  • x integer Used by "mouseMove", "mouseDown" and "mouseUp". X position of the mouse, in screen space. (default nil)
  • y integer Used by "mouseMove", "mouseDown" and "mouseUp". Y position of the mouse, in screen space. (default nil)
PTOnEvent (type, callback)
Set a callback for an event.

Parameters:

  • type string Event type code. Options are: "null", "start", "quit", "reset", "keyDown", "keyUp", "mouseMove", "mouseDown", "mouseUp"
  • callback function Function body to call, with the PTEvent object as an argument.
PTOnMouseOver (callback)
Set a callback for when the mouse moves over a new PTActor/PTBackground/PTSprite.

Parameters:

  • callback function Function body to call, with the moused-over object as an argument.
PTOnRenderFrame (callback)
Set a callback for before rendering the current frame to the screen. Useful for animating object positions.

Parameters:

  • callback function Function body to call.
PTOnTalkSkipWhileGrabbed (callback)
Set a callback for when the user indicates they wish to skip a single spoken line. This callback will be called if the user clicks the mouse or presses [.] while the input is grabbed.

Parameters:

  • callback function Function body to call.
PTOnFastForwardWhileGrabbed (callback)
Set a callback for when the user indicates they wish to fast-forward a thread. This callback will be called if the user presses [Escape] while the input is grabbed.

Parameters:

  • callback function Function body to call.
PTOnRoomLoad (name, func)
Set a callback for setting up a particular room. This code will be called whenever PTSwitchRoom is triggered, and also during restoration of a save game. It is recommended to use this callback function to e.g. arrange the room contents based on variables from the PTVars.

Parameters:

  • name string Name of the room.
  • func function Function body to call, with an optional argument for context data.
PTOnRoomUnload (name, func)
Set a callback for unloading a particular room. This code will be called whenever PTSwitchRoom is triggered.

Parameters:

  • name string Name of the room.
  • func function Function body to call, with an optional argument for context data.
PTOnRoomEnter (name, func)
Set a callback for switching to a particular room. This code will only be called during gameplay, i.e. when PTSwitchRoom is triggered. For code that sets up the state of the room, use PTOnRoomLoad.

Parameters:

  • name string Name of the room.
  • func function Function body to call, with an optional argument for context data.
PTOnRoomExit (name, func)
Set a callback for switching away from a room.

Parameters:

  • name string Name of the room.
  • func function Function body to call, with an optional argument for context data.
PTOnLoadState (callback)
Set the callback to run when loading a game state. Perentie will first load all of your game's code, then read the save file, then call this callback with the state contents, then apply that state to the running game. You can use this as a hook to e.g. check for an earlier game version and apply manual variable fixups to the state.

Parameters:

  • callback function Function body to call. Takes the state object as an argument.
PTOnSaveState (callback)
Set the callback to run when saving a game state. Perentie will first generate a state from the running game, call this callback with the state contents, then write that state to a file. Ideally you shouldn't ever need this.

Parameters:

  • callback function Function body to call. Takes the state object as an argument.

Input

PTGetMousePos ()
Get the last recorded mouse position.

Returns:

  1. integer X coordinate in screen space.
  2. integer Y coordinate in screen space.
PTGrabInput ()
Grab the player's input. For the verb thread, mouse clicks will be remapped to advancing any speech on the screen, and escape will fast-forward.
PTReleaseInput ()
Release the player's input.
PTGetInputGrabbed ()
Return whether the player's input is grabbed.

Returns:

    boolean Whether the input is grabbed.
PTUsingTouch ()
Return whether the engine has seen a touchscreen input. Perentie will translate touch events to mouse inputs; a normal tap will translate to a left mouse click, a tap held for 500ms will translate to a right mouse click, and any other interaction will count as a left mouse click and drag. This can be used as a check to e.g. enable touch-specific UI elements. Be aware that it is possible for a system to have both touch and mouse inputs.

Returns:

    boolean Whether a touchscreen input has been seen.
PTGetMouseOver ()
Get the current object which the mouse is hovering over

Returns:

    table The object (PTActor/PTBackground/PTSprite), or nil.

Walk box

PTPoint
Point structure

Fields:

  • x integer X coordinate.
  • y integer Y coordinate.
PTPoint (x, y)
Create a new point.

Parameters:

  • x integer X coordinate.
  • y integer Y coordinate.

Returns:

    PTPoint The new point.
PTWalkBox
Walk box structure. Perentie uses the SCUMM walk box algorithm. All boxes are quads, which can be any convex shape. Two boxes are considered to be connected if they both have a fully horizontal or vertical edge which is coincident; that is, fully or partially overlapping. Boxes cover the pixel area inclusive of the coordinates; it's perfectly acceptable to make a 1px path where each pair of corners is the same.

Fields:

  • _type string "PTWalkBox"
  • ul PTPoint Coordinates of upper-left corner.
  • ur PTPoint Coordinates of upper-right corner.
  • lr PTPoint Coordinates of lower-right corner.
  • ll PTPoint Coordinates of lower-left corner.
  • z integer Depth coordinate; a higher number renders to the front. Used for setting the depth of PTActors.
  • id integer Internal ID of the walk box. Used internally by the box matrix. (default nil)
  • on_enter function Callback for when an actor enters a walkbox, with the walk box and actor as arguments. (default nil)
PTWalkBox (ul, ur, lr, ll, z)
Create a new walk box.

Parameters:

  • ul PTPoint Coordinates of upper-left corner.
  • ur PTPoint Coordinates of upper-right corner.
  • lr PTPoint Coordinates of lower-right corner.
  • ll PTPoint Coordinates of lower-left corner.
  • z integer Depth coordinate; a higher number renders to the front. Used for setting the depth of PTActors.

Returns:

    PTWalkBox The new walk box.
PTOnEnterWalkBox (walkbox, callback)
Set a callback for when an actor enters a walk box.

Parameters:

  • walkbox PTWalkBox Walk box to use.
  • callback function Function body to call, with the walk box and actor as arguments.
PTGenLinksFromWalkBoxes (boxes)
Generate a list of connections between PTWalkBox objects. Most of the time you won't need to call this yourself; PTRoomSetWalkBoxes will do this for you.

Parameters:

Returns:

    table List of index pairs, each describing two directly connected walk boxes in the list.
PTGenWalkBoxMatrix (n, links)
Generate a matrix describing the shortest path between walk boxes. Most of the time you won't need to call this yourself; PTRoomSetWalkBoxes will do this for you.

Parameters:

  • n int Number of walk boxes.
  • links table List of index pairs, each describing two directly connected walk boxes.

Returns:

    table N x N matrix describing the shortest route between walk boxes; e.g. when starting from box ID i and trying to reach box ID j, result[i][j] is the ID of the next box you need to travel through in order to take the shortest path, or 0 if there is no path.

Actors

PTActor
Actor structure.

Fields:

  • _type string "PTActor"
  • x integer X coordinate in room space. (default 0)
  • y integer Y coordinate in room space. (default 0)
  • z integer Depth coordinate; a higher number renders to the front. (default 0)
  • visible boolean Whether the actor is rendered to the screen. (default true)
  • room PTRoom The room the actor is located. (default nil)
  • sprite table The PTBackground/PTSprite object used for drawing. Perentie will proxy this; you only need to add the actor object to the rendering list. (default nil)
  • talk_x integer X coordinate in actor space for talk text. (default 0)
  • talk_y integer Y coordinate in actor space for talk text. (default 0)
  • talk_img PTBackground Handle used by the engine for caching the rendered talk text. (default nil)
  • talk_font PTFont Font to use for rendering talk text. (default nil)
  • talk_colour table Colour to use for rendering talk text. (default { 0xff 0xff 0xff })
  • talk_next_wait integer The millisecond count at which to remove the talk text. (default 0)
  • facing integer Direction of the actor; angle in degrees clockwise from north. (default 0)
  • anim_stand string Name of the sprite animation to use for standing. (default "stand")
  • anim_walk string Name of the sprite animation to use for walking. (default "walk")
  • anim_talk string Name of the sprite animation to use for talking. (default "talk")
  • use_walkbox boolean Whether the actor snaps to the room's walkboxes. (default true)
PTActor (name[, x=0[, y=0[, z=0]]])
Create a new actor.

Parameters:

  • name string Name of the actor.
  • x integer X coordinate in room space. (default 0)
  • y integer Y coordinate in room space. (default 0)
  • z integer Depth coordinate; a higher number renders to the front. (default 0)

Returns:

    PTActor The new actor.
PTActorSetWalkBox (actor, box)
Set an actor's walk box.

Parameters:

PTSetActorWaitAfterTalk (enable)
Set whether to automatically wait after a PTActor starts talking. If enabled, this means threads can make successive calls to PTActorTalk and the engine will treat them as a conversation; you don't need to explicitly call PTWaitForActor after each one. If you want to do manual conversation timing, disable this feature. Defaults to true.

Parameters:

  • enable boolean Whether to wait after talking.
PTGetTalkBaseDelay ()
Get the base delay for talking. When a PTActor is talking, this is the fixed amount of time to wait, regardless of text length.

Returns:

    integer The base delay, in milliseconds. Defaults to 1000.
PTGetTalkCharDelay ()
Get the character delay for talking. When a PTActor is talking, this is the variable amount of time to wait, as a multiple of the number of characters in the text.

Returns:

    integer The character delay, in milliseconds. Defaults to 85.
PTSetTalkBaseDelay (delay)
Set the base delay for talking.

Parameters:

  • delay integer The base delay, in milliseconds.
PTSetTalkCharDelay (delay)
Set the chracter delay for talking.

Parameters:

  • delay integer The character delay, in milliseconds.
PTActorTalk (actor, message[, font=nil[, colour=nil[, duration=nil]]])
Make an actor talk. This will trigger the actor's talk animation, as defined in actor.anim_talk. By default, this will wait the thread until the actor finishes talking. You can disable this by calling PTSetActorWaitAfterTalk.

Parameters:

  • actor PTActor The actor.
  • message string Message to show on the screen.
  • font PTFont Font to use. Defaults to actor.talk_font (default nil)
  • colour table Inner colour; list of 3 8-bit numbers. Defaults to actor.talk_colour. (default nil)
  • duration integer Duration of the message, in milliseconds. By default this varies based on the length of the message; see PTGetTalkBaseDelay and PTGetTalkCharDelay. (default nil)
PTActorSilence (actor)
Make an actor stop talking. This will remove any speech bubble, and trigger the actor's stand animation, as defined in actor.anim_stand.

Parameters:

PTActorSleep (actor, millis)
Sleep the current thread. This is mechanically the same as PTSleep, however it uses the same timer as PTActorTalk, meaning it can be skipped by clicking the mouse. This is useful for e.g. dramatic pauses in dialogue.

Parameters:

  • actor PTActor The actor.
  • millis integer Time to wait in milliseconds.
PTActorSetWalk (actor, x, y[, facing=nil])
Set an actor moving towards a point in the room.

Parameters:

  • actor PTActor Actor to modify.
  • x integer X coordinate in room space.
  • y integer Y coordinate in room space.
  • facing integer Direction to face the actor in at the destination. (default nil)
PTAddActor (actor)
Add an actor to the engine state.

Parameters:

PTRemoveActor (actor)
Remove an actor from the engine state.

Parameters:

  • actor PTActor The actor to remove.
PTActorSetRoom (actor, room[, x=nil[, y=nil[, z=nil]]])
Move an actor into a different room.

Parameters:

  • actor PTActor The actor to move.
  • room PTRoom Destination room.
  • x integer X position for actor. (default nil)
  • y integer Y position for actor. (default nil)
  • z integer Depth coordinate; a higher number renders to the front. (default nil)
PTActorSetAnimation (actor, name[, facing=0])
Set the current animation to play on an actor's sprite.

Parameters:

  • actor PTActor The actor to modify.
  • name string Name of the animation.
  • facing integer Direction of the animation; angle in degrees clockwise from north. (default 0)

Returns:

    boolean Whether the current animation was changed.

Rendering

PTImage
Image structure.

Fields:

  • _type string "PTImage"
  • ptr userdata Pointer to C data.
  • boolean collision_mask Whether to use the transparency mask for collision detection. (default true)
PTImage (path[, origin_x=0[, origin_y=0[, colourkey=-1[, collision_mask=true]]]])
Load a new image.

Parameters:

  • path string Path of the image (must be 8-bit indexed or grayscale PNG).
  • origin_x integer Origin x coordinate, relative to top-left corner. (default 0)
  • origin_y integer Origin y coordinate, relative to top-left corner. (default 0)
  • colourkey integer Palette index to use as colourkey. (default -1)
  • collision_mask boolean Whether to use the transparency mask for collision detection. (default true)

Returns:

    PTImage The new image.
PTImageSequence (path_format, start, finish[, origin_x=0[, origin_y=0]])
Load a sequence of images.

Parameters:

  • path_format string Path of the image (must be 8-bit indexed or grayscale PNG), with %d placeholder for index.
  • start integer Start index.
  • finish integer End index (inclusive).
  • origin_x integer Origin x coordinate, relative to top-left corner. (default 0)
  • origin_y integer Origin y coordinate, relative to top-left corner. (default 0)

Returns:

    table List of new images.
PT9Slice
9-slice image reference structure.

Fields:

  • _type string "PT9Slice"
  • image PTImage Image to use as an atlas.
  • x1 integer X coordinate in image space of left slice plane.
  • y1 integer Y coordinate in image space of top slice plane.
  • x2 integer X coordinate in image space of right slice plane.
  • y2 integer Y coordinate in image space of bottom slice plane.
  • width integer Width of resulting 9-slice image.
  • height integer Height of resulting 9-slice image.
PT9Slice (image, x1, y1, x2, y2[, width=0[, height=0]])
Create a new 9-slice image reference.

Parameters:

  • image PTImage Image to use as an atlas.
  • x1 integer X coordinate in image space of left slice plane.
  • y1 integer Y coordinate in image space of top slice plane.
  • x2 integer X coordinate in image space of right slice plane.
  • y2 integer Y coordinate in image space of bottom slice plane.
  • width integer Width of resulting 9-slice image. (default 0)
  • height integer Height of resulting 9-slice image. (default 0)

Returns:

    PT9Slice The new image reference.
PT9SliceCopy (slice, width, height)
Create a copy of a 9-slice image reference with different dimensions.

Parameters:

  • slice PTSlice 9-slice image reference to use as a reference.
  • width integer Width of resulting 9-slice image.
  • height integer Height of resulting 9-slice image.

Returns:

    PT9Slice The new image reference.
PTGetImageDims (image)
Get the dimensions of an image.

Parameters:

Returns:

  1. integer Width of the image.
  2. integer Height of the image.
PTGetImageOrigin (image)
Get the origin position of an image. This is the position in image coordinates to use as the origin point; so if the image is e.g. used by a PTBackground object with position (x, y), the image will be rendered with the top-left at position (x - origin_x, y - origin_y).

Parameters:

Returns:

  1. integer X coordinate in image space.
  2. integer Y coordinate in image space.
PTSetImageOrigin (image, x, y)
Set the origin position of an image.

Parameters:

  • image PTImage Image to query.
  • x integer X coordinate in image space.
  • y integer Y coordinate in image space.
PTSetImageOriginSimple (image, origin)
Set the origin position of an image.

Parameters:

  • image PTImage Image to query.
  • origin string Origin location; one of "top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right"
PTDrawImage (image, x, y, flags)
Blit a PTImage/PT9Slice to the screen. Normally not called directly; Perentie will render everything in the display lists managed by PTRoomAddObject and PTGlobalAddObject.

Parameters:

  • image table Image to blit to the screen.
  • x integer X coordinate in screen space.
  • y integer Y coordinate in screen space.
  • flags integer Flags for rendering the image.
PTTestImageCollision (image, x, y, flags, collision_mask)
Perform a collision test for an image.

Parameters:

  • image table PTImage/PT9Slice to test.
  • x integer X coordinate in image space.
  • y integer Y coordinate in image space.
  • flags integer Flags for rendering the image.
  • collision_mask boolean If true, test the masked image (i.e. excluding transparent areas), else use the image's bounding box.
PTGetPalette ()
Return the current palette.

Returns:

    table A table containing colours from the current palette. Each colour is a table containing three 8-bit numbers.
PTSetPaletteRemapper ([remapper="none"[, mode="nearest"]])
Set the automatic palette remapper to use. This will remove any of the current dithering hints and replace them with the output of the remapper. Subsequent hints can be added.

Parameters:

  • remapper string Remapper to use. Choices are: "none", "ega" (default "none")
  • mode string Default dither mode to use. Choices are: "nearest", "half", "quarter", "quarter-alt", "half-nearest", "quarter-nearest". (default "nearest")
PTSetAutoClearScreen (val)
Set whether to clear the screen at the start of every frame

Parameters:

  • val boolean true if the screen is to be cleared, false otherwise.
PTSetOverscanColour (colour)
Set the overscan colour. For DOS, this is the colour used for the non-drawable area on a CRT/LCD monitor. For SDL, this is the colour used for filling the spare area around the viewport.

Parameters:

  • colour table Table containing three 8-bit numbers.
PTSetDitherHint (src, dither_type, dest_a, dest_b)
Set a dithering hint. Used for remapping a VGA-style palette to a smaller colour range such as EGA or CGA.

Parameters:

  • src table Source colour, table containing three 8-bit numbers.
  • dither_type string Type of dithering algorithm to use. Choices are: "none", "fill-a", "fill-b", "quarter", "quarter-alt", "half"
  • dest_a table Destination mixing colour A, table containing three 8-bit numbers.
  • dest_b table Destination mixing colour B, table containing three 8-bit numbers.
PTBackground
Background structure.

Fields:

  • _type string "PTBackground"
  • x integer X coordinate. (default 0)
  • y integer Y coordinate. (default 0)
  • z integer Depth coordinate; a higher number renders to the front. (default 0)
  • parallax_x float X parallax scaling factor. (default 1)
  • parallax_y float Y parallax scaling factor. (default 1)
  • collision boolean Whether to test this object's sprite mask for collisions; e.g. when updating the current PTGetMouseOver object. (default false)
  • visible boolean Whether to draw this object to the screen. (default true)
PTBackground (image[, x=0[, y=0[, z=0[, collision=false]]]])
Create a new background.

Parameters:

  • image PTImage Image to use.
  • x integer X coordinate. (default 0)
  • y integer Y coordinate. (default 0)
  • z integer Depth coordinate; a higher number renders to the front. (default 0)
  • collision boolean Whether to test this object's sprite mask for collisions; e.g. when updating the current PTGetMouseOver object. (default false)

Returns:

    PTBackground The new background.
PTAnimation
Animation structure.

Fields:

  • _type string "PTAnimation"
  • name string Name of the animation.
  • frames table List of PTImage objects; one per frame.
  • rate integer Frame rate to use for playback. (default 0)
  • facing integer Direction of the animation; angle in degrees clockwise from north. (default 0)
  • looping boolean Whether to loop the animation when completed. (default true)
  • current_frame integer The current frame in the sequence to display. (default 0)
  • next_wait integer The millisecond count at which to show the next frame. (default 0)
  • flags integer Flags for rendering the image. (default 0)
PTAnimation (name, frames[, rate=0[, facing=0[, h_mirror=false[, v_mirror=false[, looping=true]]]]])
Create a new animation.

Parameters:

  • name string Name of the animation.
  • frames table List of PTImage objects; one per frame.
  • rate integer Frame rate to use for playback. (default 0)
  • facing integer Direction of the animation; angle in degrees clockwise from north. (default 0)
  • h_mirror boolean Whether the animation can be mirrored horizontally. (default false)
  • v_mirror boolean Whether the animation can be mirrored vertically. (default false)
  • looping boolean Whether to loop the animation when completed. (default true)

Returns:

    PTAnimation The new animation.
PTSprite
Sprite structure.

Fields:

  • _type string "PTSprite"
  • animations table Table of PTAnimation objects.
  • x integer X coordinate. (default 0)
  • y integer Y coordinate. (default 0)
  • z integer Depth coordinate; a higher number renders to the front. (default 0)
  • parallax_x float X parallax scaling factor. (default 1)
  • parallax_y float Y parallax scaling factor. (default 1)
  • anim_index integer Index of the current animation from the animations table. (default nil)
  • anim_flags integer Transformation flags to be applied to the frames. (default 0)
  • collision boolean Whether to test this object's sprite mask for collisions; e.g. when updating the current PTGetMouseOver object. (default false)
  • visible boolean Whether to draw this object to the screen. (default true)
PTSprite (animations[, x=0[, y=0[, z=0]]])
Create a new sprite.

Parameters:

  • animations table Table of PTAnimation objects.
  • x integer X coordinate. (default 0)
  • y integer Y coordinate. (default 0)
  • z integer Depth coordinate; a higher number renders to the front. (default 0)

Returns:

    PTSprite The new sprite.
PTSpriteSetAnimation (sprite, name[, facing=0])
Set the current animation to play on a sprite.

Parameters:

  • sprite PTSprite The sprite to modify.
  • name string Name of the animation.
  • facing integer Direction of the animation; angle in degrees clockwise from north. (default 0)

Returns:

    boolean Whether the current animation was changed.
PTSpriteIncrementFrame (object)
Increment a sprite's current animation frame. This does not take into account the playback rate.

Parameters:

PTGroup
Group structure.

Fields:

  • _type string "PTGroup"
  • objects table List of member objects.
  • x integer X coordinate.
  • y integer Y coordinate.
  • z integer Depth coordinate; a higher number renders to the front.
  • origin_x integer Origin x coordinate, relative to top-left corner..
  • origin_y integer Origin y coordinate, relative to top-left corner.
  • visible boolean Whether to draw this object to the screen. (default true)
PTGroup (objects, x, y, z, origin_x, origin_y)
Create a new group.

Parameters:

  • objects table List of member objects.
  • x integer X coordinate.
  • y integer Y coordinate.
  • z integer Depth coordinate; a higher number renders to the front.
  • origin_x integer Origin x coordinate, relative to top-left corner..
  • origin_y integer Origin y coordinate, relative to top-left corner.

Returns:

    PTGroup The new group.
PTGroupAddObject (group, object)
Add a renderable (PTActor/PTBackground/PTSprite/PTGroup) object to a group rendering list.

Parameters:

  • group PTGroup Group to add object to.
  • object table Object to add.
PTGroupRemoveObject (group, object)
Remove a renderable (PTActor/PTBackground/PTSprite/PTGroup) object from a group rendering list.

Parameters:

  • group PTGroup Group to remove object from.
  • object table Object to remove.
PTIterObjects (objects[, reverse=false[, visible_only=true]])
Iterate through a list of renderable (PTActor/PTBackground/PTSprite/PTGroup) objects. PTGroups will be flattened, leaving only PTActor/PTBackground/PTSprite objects with adjusted positions.

Parameters:

  • objects table List of objects.
  • reverse boolean Whether to iterate in reverse. (default false)
  • visible_only boolean Whether to only output visible objects. (default true)

Returns:

    function An iterator function that returns an object, a x coordinate and a y coordinate.
PTGetImageFromObject (object)
Fetch the image to use when rendering a PTActor/PTBackground/PTSprite object.

Parameters:

  • object table The object to query.

Returns:

  1. table The PTImage or PT9Slice for the current frame.
  2. integer Flags to render the image with.
PTGlobalAddObject (object)
Add a renderable (PTActor/PTBackground/PTSprite/PTGroup) object to the global rendering list.

Parameters:

  • object table Object to add.
PTGlobalRemoveObject (object)
Remove a renderable (PTActor/PTBackground/PTSprite/PTGroup) object from the global rendering list.

Parameters:

  • object table Object to remove.

Movement

PTLinear ([points={0.0 1.0}])
Return a function for linear interpolation.

Parameters:

  • points table List of control points to interpolate between. (default {0.0 1.0})

Returns:

    function Callable that takes a progress value from 0.0-1.0 and returns an output from 0.0-1.0.
PTCubicBezier (x1, y1, x2, y2)
Return a function for a unit cubic bezier curve. Start point is always (0, 0), end point is always (1, 1).

Parameters:

  • x1 float Curve control point 1 x coordinate.
  • y1 float Curve control point 1 y coordinate.
  • x2 float Curve control point 2 x coordinate.
  • y2 float Curve control point 2 y coordinate.

Returns:

    function Callable that takes a progress value from 0.0-1.0 and returns an output from 0.0-1.0.
PTTimingFunction ([timing="linear"])
Return a preset timing function. A timing function is a callable that accepts a progress value between 0.0-1.0, and returns an output value between 0.0-1.0. The presets are the same as in the CSS animation-timing-function specification. "linear" - Even speed. "ease" - Increases in speed towards the middle of the animation, slowing back down at the end. "ease-in" - Starts off slowly, with the speed increasing until complete. "ease-out" - Starts off quickly, with the speed decreasing until complete. "ease-in-out" - Starts off slowly, speeds up in the middle, and then the speed decreases until complete.

Parameters:

  • timing any Alias of a builtin function, or a timing function such as one generated from PTCubicBezier or PTLinear. (default "linear")

Returns:

    The timing function.
PTMoveRef
Movement reference structure.

Fields:

  • _type string "PTMoveRef"
  • timing function Timing function, such as returned from PTTimingFunction.
  • start_time integer Movement start time, in milliseconds.
  • duration integer Movement duration, in milliseconds.
  • object table Any object with "x" and "y" parameters to move.
  • x_a integer Start X coordinate of the object in room space.
  • y_a integer Start Y coordinate of the object in room space.
  • x_b integer Finish X coordinate of the object in room space.
  • y_b integer Finish Y coordinate of the object in room space.
  • while_paused boolean Whether to move the object while the game is paused.
PTMoveRef (object, x, y, start_time, duration, timing, while_paused)
Create a new movement reference.

Parameters:

  • object table Any object with "x" and "y" parameters to move.
  • x integer Finish X coordinate of the object in room space.
  • y integer Finish Y coordinate of the object in room space.
  • start_time integer Movement start time, in milliseconds.
  • duration integer Movement duration, in milliseconds.
  • timing function Timing function, such as returned from PTTimingFunction.
  • while_paused boolean Whether to move the object while the game is paused.

Returns:

    PTMoveRef The new movement refrence.
PTMoveObject (object, x, y, duration, timing[, while_paused=false])
Move an object smoothly to a destination point. On every rendered frame, Perentie will adjust the "x" and "y" parameters on the target object to move it to the destination, with the speed determined by a duration and a timing function. You can only have one movement instruction per object. If an existing move instruction is found for an object, Perentie will replace it.

Parameters:

  • object table Any object with "x" and "y" parameters.
  • x integer Absolute x coordinate to move towards.
  • y integer Absolute y coordinate to move towards.
  • duration integer Duration of movement in milliseconds.
  • timing any Timing function or alias to use, same as timing argument of PTTimingFunction.
  • while_paused boolean Whether to move the object while the game is paused. (default false)
PTMoveObjectRelative (object, dx, dy, duration, timing[, while_paused=false])
Move an object smoothly to a destination point relative to the object's current position.

Parameters:

  • object table Any object with "x" and "y" parameters
  • dx integer X distance relative to the object's current position to move towards.
  • dy integer Y distance relative to the object's current position to move towards.
  • duration integer Duration of movement in milliseconds.
  • timing any Timing function or alias to use, same as timing argument of PTTimingFunction.
  • while_paused boolean Whether to move the object while the game is paused. (default false)
PTObjectIsMoving (object)
Check if an object is moving.

Parameters:

  • object table Any object with "x" and "y" parameters

Returns:

    boolean Whether the object is moving.
PTSimplexShake (x_amplitude, y_amplitude, x_frequency, y_frequency)
Return a function for shaking using simplex noise.

Parameters:

  • x_amplitude float X amplitude of the shake.
  • y_amplitude float Y amplitude of the shake.
  • x_frequency float X frequency of the shake, in Hz.
  • y_frequency float Y frequency of the shake, in Hz.

Returns:

    function Callable that takes a time value in millieseconds and returns an (x, y) pair of coordinates.
PTShakeRef
Shake reference structure

Fields:

  • _type string "PTShakeRef"
  • start_time integer Shake start time, in milliseconds.
  • duration integer Movement duration, in milliseconds.
  • object table Any object with "sx" and "sy" parameters to move.
  • shake_func function Shake function to use, such as the return value of PTSimplexShake.
  • while_paused boolean Whether to shake the object while the game is paused.
PTShakeRef (object, shake_func, start_time, duration, while_paused)
Create a new shake reference.

Parameters:

  • object table Any object with "sx" and "sy" parameters to move.
  • shake_func function Shake function to use, such as the return value of PTSimplexShake.
  • start_time integer Shake start time, in milliseconds.
  • duration integer Movement duration, in milliseconds.
  • while_paused boolean Whether to shake the object while the game is paused.
PTShakeObject (object, duration, shake_func[, while_paused=false])
Shake an object without changing its position. On every rendered frame, Perentie will adjust the "sx" and "sy" parameters on the target object to adjust the offset from the (x, y) position. You can only have one shake instruction per object. If an existing shake instruction is found for an object, Perentie will replace it.

Parameters:

  • object table Any object with "sx" and "sy" parameters.
  • duration integer Duration of shake in milliseconds.
  • shake_func function Shake function to use, such as the return value of PTSimplexShake.
  • while_paused boolean Whether to shake the object while the game is paused. (default false)

GUI controls

PTPanel
Panel structure

Fields:

  • _type string "PTPanel"
  • image table ${PTImage}/${PT9Slice} to use as a background.
  • x integer X coordinate in screen space.
  • y integer Y coordinate in screen space.
  • z integer Depth coordinate; a higher number renders to the front.
  • width integer Width of panel.
  • height integer Height of panel.
  • visible boolean Whether panel is visible.
  • objects table Child widgets held by panel.
PTPanel (image, x, y, width, height[, visible=true])
Create a new panel.

Parameters:

  • image table ${PTImage}/${PT9Slice} to use as a background.
  • x integer X coordinate in screen space.
  • y integer Y coordinate in screen space.
  • width integer Width of panel.
  • height integer Height of panel.
  • visible boolean Whether panel is visible. (default true)

Returns:

    PTPanel The new panel.
PTHorizSlider
Horizontal slider structure.

Fields:

  • _type string "PTHorizSlider"
  • value integer Start value of the slider.
  • min_value integer Minimum permitted value.
  • max_value integer Maximum permitted value.
  • images table Table of ${PTImage}/${PT9Slice} to use. Allowed keys: "default", "hover", "active", "disabled", "track"
  • x integer X coordinate of widget.
  • y integer Y coordinate of widget.
  • z integer Depth coordinate; a higher number renders to the front.
  • width integer Width of the slider.
  • height integer Height of the slider.
  • track_size integer Height of the track image.
  • handle_size integer Width of the handle image.
  • hover boolean Whether the widget is currently hovered over.
  • active boolean Whether the widget is currently active.
  • disabled boolean Whether the widget is disabled.
  • visible boolean Whether the widget is visible.
  • origin_x integer X coordinate of the widget offset.
  • origin_y integer Y coordinate of the widget offset.
  • change_callback function Callback to run when slider changes position.
  • set_callback function Callback to run when the value is set.
  • objects table Child objects held by widget.
PTHorizSlider (images, x, y, width, height, track_size, handle_size, value, min_value, max_value, change_callback, set_callback)
Create a new horizontal slider control.

Parameters:

  • images table Table of ${PTImage}/${PT9Slice} to use. Allowed keys: "default", "hover", "active", "disabled", "track"
  • x integer X coordinate.
  • y integer Y coordinate.
  • width integer Width of the control.
  • height integer Height of the control.
  • track_size integer Height of the track image.
  • handle_size integer Width of the handle image.
  • value integer Start value of the slider.
  • min_value integer Minimum permitted value.
  • max_value integer Maximum permitted value.
  • change_callback function Callback to run when slider changes position.
  • set_callback function Callback to run when the value is set.

Returns:

    PTHorizSlider The new horizontal slider.
PTSliderPosToValue (slider, pos)
Convert a slider position to a value.

Parameters:

  • slider any Slider object to modify.
  • pos integer New slider position, in screen units.

Returns:

    integer Slider value.
PTSliderValueToPos (slider, value)
Convert a slider value to a position.

Parameters:

  • slider any Slider object to modify.
  • value integer New value to have.

Returns:

    integer Slider position, in screen units.
PTSliderSetValue (slider, value)
Set a slider to a value.

Parameters:

  • slider any Slider object to modify.
  • value integer New value to have.
PTButton
Button structure.

Fields:

  • _type string "PTButton"
  • images table Table of ${PTImage}/${PT9Slice} to use. Allowed keys: "default", "hover", "active", "disabled"
  • x integer X coordinate.
  • y integer Y coordinate.
  • z integer Depth coordinate; a higher number renders to the front.
  • width integer Width of the control.
  • height integer Height of the control.
  • objects table Child objects held by widget.
  • hover boolean Whether the widget is currently hovered over.
  • active boolean Whether the widget is currently active.
  • disabled boolean Whether the widget is disabled.
  • visible boolean Whether the widget is visible.
  • origin_x integer X coordinate of the widget offset.
  • origin_y integer Y coordinate of the widget offset.
  • callback function Callback to run when the button is activated.
PTButton (images, x, y, width, height, objects, callback)
Create a new button control.

Parameters:

  • images table Table of ${PTImage}/${PT9Slice} to use. Allowed keys: "default", "hover", "active", "disabled"
  • x integer X coordinate.
  • y integer Y coordinate.
  • width integer Width of the control.
  • height integer Height of the control.
  • objects table Child objects held by widget.
  • callback function Callback to run when the button is activated.

Returns:

    PTButton The new button.
PTRemovePanel (panel)
Remove a panel from the engine state.

Parameters:

  • panel PTPanel The panel to remove.
PTPanelAddObject (panel, object)
Add a renderable (PTBackground/PTSprite/PTGroup) object to the panel rendering list.

Parameters:

  • panel PTPanel Panel to modify.
  • object table Object to add.
PTPanelRemoveObject (panel, object)
Remove a renderable (PTBackground/PTSprite/PTGroup) object from the panel rendering list.

Parameters:

  • panel PTPanel Panel to modify.
  • object table Object to add.

Text

PTFont
Bitmap font structure.

Fields:

  • _type string "PTFont"
  • ptr userdata Pointer to C data.
PTFont (path)
Create a new bitmap font.

Parameters:

  • path string Path of the bitmap font (must be BMFont V3 binary).

Returns:

    PTFont The new font.
PTText (text, font[, width=200[, align="left"[, colour={ 0xff 0xff 0xff }[, border={ 0x00 0x00 0x00 }]]]])
Create an new image containing rendered text.

Parameters:

  • text string Unicode text to render.
  • font PTFont Font object to use.
  • width integer Width of bounding area in pixels. (default 200)
  • align string Text alignment; one of "left", "center" or "right". (default "left")
  • colour table Inner colour; list of 3 8-bit numbers. (default { 0xff 0xff 0xff })
  • border table Border colour; list of 3 8-bit numbers. (default { 0x00 0x00 0x00 })

Returns:

    PTImage The new image.

Audio

PTWave
Wave structure

Fields:

  • _type string "PTWave"
  • ptr userdata Pointer to C data.
PTWave (path)
Load a new wave file.

Parameters:

  • path string Path of the wave file.

Returns:

    PTWave The new wave.
PTFreqToMIDI (freq)
Convert a tone frequency to a position on the MIDI pitch scale. The MIDI scale is linear, with an increase of 1 unit per semitone and A440 assigned to 69. Note that the output of this function is not rounded to the nearest integer, nor is it bounded to 0-127, which are required for MIDI usage.

Parameters:

  • freq float Tone frequency, in Hz.

Returns:

    float MIDI pitch.
PTMIDIToFreq (midi)
Convert a MIDI pitch to a tone frequency.

Parameters:

  • midi float MIDI pitch.

Returns:

    float Tone frequency, in Hz.
PTFreqToIFS (freq)
Convert a tone frequency to an Inverse Frequency Sound value. This is the value expected by the PC speaker's square wave generator.

Parameters:

  • freq float Tone frequency, in Hz.

Returns:

    integer IFS, in PC speaker timing units.
PTPCSpeakerData
PC speaker data structure.

Fields:

  • _type string "PTPCSpeakerData"
  • name string Name of the sample. (default nil)
  • ptr userdata Pointer to C data.
PTPCSpeakerData (data[, playback_rate=140])
Create a new PC speaker data buffer. This can be played back using PTPCSpeakerPlayData.

Parameters:

  • data table List of IFS values, in PC speaker timing units.
  • playback_rate integer Playback rate for data, in Hz. Defaults to 140, which was the standard rate used by Apogee. (default 140)

Returns:

    PTPCSpeakerData The new data buffer.
PTPCSpeakerDataFreq (data[, playback_rate=140])
Create a new PC speaker data buffer, using tone frequency values. This can be played back using PTPCSpeakerPlayData.

Parameters:

  • data table List of tone frequencies, in Hz.
  • playback_rate integer Playback rate for data, in Hz. Defaults to 140, which was the standard rate used by Apogee. (default 140)

Returns:

    PTPCSpeakerData The new data buffer.
PTPCSpeakerPlayTone (freq)
Play a square wave tone on the PC speaker. The note will play until it is stopped by a call to PTPCSpeakerStop.

Parameters:

  • freq number Audio frequency of the tone.
PTPCSpeakerPlaySample (wave)
Play an audio sample through the PC speaker. This abuses the same timer-driven impulse trick that Access Software's RealSound uses, producing ~6-bit PCM audio. This will not play back if DOS Perentie is running inside Windows.

Parameters:

  • wave PTWave PTWave to play back. Must be mono unsigned 8-bit samples, either 8000Hz or 16000Hz sample rate.
PTPCSpeakerPlayData (data)
Play a data buffer through the PC speaker.

Parameters:

PTPCSpeakerStop ()
Stop all playback through the PC speaker.
PTPCSpeakerLoadIFS (path)
Load a PC speaker sound file in Inverse Frequency Sound format.

Parameters:

  • path string The path to the file.

Returns:

    table List of PTPCSpeakerData objects for each sound in the file.
PTRadLoad (path)
Load a music file in Reality Adlib Tracker format.

Parameters:

  • path string The path to the file.

Returns:

    boolean Whether the file was successfully loaded.
PTRadPlay ()
Start playing the music loaded in the RAD player.
PTRadStop ()
Stop playing the music loaded in the RAD player.
PTRadGetPath ()
Get the path of the currently playing file in the RAD player.

Returns:

    string Path of the current playing RAD file.
PTRadGetVolume ()
Get the master volume of the RAD player.

Returns:

    integer Volume, ranging from 0 to 255.
PTRadSetVolume (volume)
Set the master volume of the RAD player.

Parameters:

  • volume integer Volume, ranging from 0 to 255.
PTRadGetPosition ()
Get the playback head position of the RAD player.

Returns:

  1. integer Order list index.
  2. integer Line of the pattern.
PTRadSetPosition ([order=0[, line=0]])
Set the playback head position of the RAD player.

Parameters:

  • order integer Order list index. (default 0)
  • line integer Line of the pattern. (default 0)
PTRadFadeIn (duration)
Start playing the music loaded in the RAD player with a volume fade-in.

Parameters:

  • duration integer Duration of fade, in milliseconds.
PTRadFadeOut (duration)
Stop playing the music loaded in the RAD player with a volume fade-out.

Parameters:

  • duration integer Duration of fade, in milliseconds.

Threading

PTStartThread (name, func, ...)
Start a function in a new thread. Perentie runs threads with cooperative multitasking; that is, a long-running thread must use a sleep function like PTSleep to yield control back to the engine.

Parameters:

  • name string Name of the thread. Must be unique.
  • func function Function to run.
  • ... Arguments to pass to the function.
PTStopThread (name, ignore_self, ignore_missing)
Stop a running thread.

Parameters:

  • name string Name of the thread.
  • ignore_self boolean If true, ignore if this is the currently running thread.
  • ignore_missing boolean If true, ignore if this thread isn't running.
PTFastForward ([enabled=true])
Fast forward the current thread. This will cause the engine to skip all sleep/wait instructions.

Parameters:

  • enabled boolean Whether to enable or disable fast forward. (default true)
PTFastForwardThread (name, ignore_missing[, enabled=true])
Fast forward the named thread. This will cause the engine to skip all sleep/wait instructions.

Parameters:

  • name string Name of the thread.
  • ignore_missing boolean If true, ignore if this thread isn't running.
  • enabled boolean Whether to enable or disable fast forward. (default true)
PTTalkSkip ()
Perform a talk skip on the current thread. If the thread is still waiting for an actor, the engine will skip the wait.
PTTalkSkipThread (name, ignore_missing)
Perform a talk skip on the named thread. If the thread is still waiting for an actor, the engine will skip the wait.

Parameters:

  • name string Name of the thread.
  • ignore_missing boolean If true, ignore if this thread isn't running.
PTThreadInFastForward ([name=nil])
Check whether a thread is in the fast forward state.

Parameters:

  • name string Name of the thread. Defaults to the current execution context. (default nil)

Returns:

    boolean Whether the thread is in the fast forward state.
PTThreadExists ([name=nil])
Check whether a thread is running.

Parameters:

  • name string Name of the thread. Defaults to the current execution context. (default nil)

Returns:

    boolean Whether the thread exists.
PTSleep (millis)
Sleep the current thread. Perentie uses co-operative multitasking; for long-running background tasks it is important to call a wait or sleep function whenever possible, even with a delay of 0. Not doing so will cause the engine to freeze up, until the thread is aborted early by the watchdog.

Parameters:

  • millis integer Time to wait in milliseconds.
PTWaitForActor (actor)
Sleep the current thread until an actor finishes the action in progress.

Parameters:

PTWaitForMoveObject (object)
Sleep the current thread until an object finishes moving.

Parameters:

PTWaitForAnimation (animation)
Sleep the current thread until a PTAnimation reaches the end.

Parameters:

PTSetWatchdog (enable)
Toggle the use of the watchdog to abort threads that take too long. Enabled by default.

Parameters:

  • enable boolean Whether to enable the watchdog.
PTSetWatchdogLimit (count)
Set the number of Lua instructions that need to elapse without a sleep before the watchdog aborts a thread. Defaults to 10000.

Parameters:

  • count integer Number of instructions.
PTOnlyRunOnce (name)
Assert that this function can't be run more than once. Usually used as a guard instruction at the top of a Lua script. Multiple invocations will raise an error.

Parameters:

  • name string Name of the script.

Rooms

PTRoom
Room structure.

Fields:

  • type string "PTRoom"
  • name string Name of the room.
  • width integer Width of the room in pixels.
  • height integer Height of the room in pixels.
  • x integer X coordinate of camera in room space.
  • y integer Y coordinate of camera in room space.
  • origin_x integer X coordinate of the camera offset in screen space.
  • origin_y integer Y coordinate of the camera offset in screen space.
  • render_list table List of renderable (PTActor/PTBackground/PTSprite/PTGroup) objects in the room.
  • boxes table List of PTWalkBox objects which make up the room's walkable area.
  • box_links table List of box ID pairs, each describing two directly connected walk boxes.
  • box_matrix table N x N matrix describing the shortest route between walk boxes; e.g. when starting from box ID i and trying to reach box ID j, box_matrix[i][j] is the ID of the next box you need to travel through in order to take the shortest path, or 0 if there is no path.
  • camera_actor PTActor Actor to follow with the room camera.
PTRoom (name, width, height)
Create a new room.

Parameters:

  • name string Name of the room.
  • width integer Width of the room in pixels.
  • height integer Height of the room in pixels.

Returns:

    PTRoom The new room.
PTRoomAddObject (room, object)
Add a renderable (PTActor/PTBackground/PTSprite/PTGroup) object to the room rendering list.

Parameters:

  • room PTRoom Room to modify.
  • object table Object to add.
PTRoomRemoveObject (room, object)
Remove a renderable (PTActor/PTBackground/PTSprite/PTGroup) object from the room rendering list.

Parameters:

  • room PTRoom Room to modify.
  • object table Object to remove.
PTRoomUpdateDepth (room)
Update the depth ordering of the objects in the room. Must be called when you change an object's z coordinate.

Parameters:

  • room PTRoom The room to modify.
PTRoomSetWalkBoxes (room, boxes)
Set the walk boxes for a room. This will replace all existing walk boxes, and regenerate the box links and box matrix for the room.

Parameters:

PTRoomGetNextBox (room, from_id, to_id)
Find the next walk box in the shortest path to reach a target walk box.

Parameters:

  • room PTRoom Room to query.
  • from_id integer ID of the starting PTWalkBox in the room.
  • to_id integer ID of the target PTWalkBox in the room.

Returns:

    PTWalkBox Next walk box in the shortest path, or nil if there is no path.
PTScreenToRoom (x, y)
Convert coordinates in screen space to room space. Uses the current room.

Parameters:

  • x integer X coordinate in screen space.
  • y integer Y coordinate in screen space.

Returns:

  1. integer X coordinate in room space.
  2. integer Y coordinate in room space.
PTRoomToScreen (x, y[, parallax_x=1[, parallax_y=1]])
Convert coordinates in room space to screen space. Uses the current room.

Parameters:

  • x integer X coordinate in room space.
  • y integer Y coordinate in room space.
  • parallax_x float X parallax scaling factor. (default 1)
  • parallax_y float Y parallax scaling factor. (default 1)

Returns:

  1. X coordinate in screen space.
  2. Y coordinate in screen space.
PTCurrentRoom ()
Return the current room.

Returns:

    PTRoom The current PTRoom.
PTGetRoom (name)
Return a room by name.

Parameters:

  • name string Name of the room.

Returns:

    PTRoom The PTRoom, or nil.
PTAddRoom (room)
Add a room to the engine state.

Parameters:

  • room PTRoom The room to add.
PTRemoveRoom (room)
Remove a room from the engine state.

Parameters:

  • room PTRoom The room to remove.
PTSwitchRoom (name, ctx)
Switch the current room. Will call the callbacks specified by PTOnRoomEnter and PTOnRoomExit.

Parameters:

  • name string Room name to switch to. Must have been added to the engine state with PTAddRoom.
  • ctx table Optional Context data to pass to the callbacks.
PTWaitForRoom (room)
Sleep the current thread until a room finishes the action in progress.

Parameters:

PTSetRoomWaitAfterTalk (enable)
Set whether to automatically wait after a PTRoom starts talking. If enabled, this means threads can make successive calls to PTRoomTalk and the engine will treat them as a conversation; you don't need to explicitly call PTWaitForRoom after each one. If you want to do manual conversation timing, disable this feature. Defaults to true.

Parameters:

  • enable boolean Whether to wait after talking.
PTRoomTalk (x, y, message[, font=nil[, colour=nil[, duration=nil]]])
Make the current room talk. This is useful for displaying disembodied voices that aren't attached to an actor. By default, this will wait the thread until the room finishes talking. You can disable this by calling PTSetRoomWaitAfterTalk.

Parameters:

  • x integer X position of message, in room coordinates.
  • y integer Y position of message, in room coordinates.
  • message string Message to show on the screen.
  • font PTFont Font to use. Defaults to actor.talk_font (default nil)
  • colour table Inner colour; list of 3 8-bit numbers. Defaults to actor.talk_colour. (default nil)
  • duration integer Duration of the message, in milliseconds. By default this varies based on the length of the message; see PTGetTalkBaseDelay and PTGetTalkCharDelay. (default nil)
PTRoomSilence ()
Make the current room stop talking. This will remove any speech bubble.
PTRoomSleep (millis)
Sleep the current thread. This is mechanically the same as PTSleep, however it uses the same timer as PTRoomTalk, meaning it can be skipped by clicking the mouse. This is useful for e.g. dramatic pauses in dialogue.

Parameters:

  • millis integer Time to wait in milliseconds.

Verbs

PTOnVerb (verb, subject, callback)
Set a callback for a single-subject verb action.

Parameters:

  • verb string Verb to use.
  • subject string Subject of the verb.
  • callback function Function body to call, with the verb and subject as arguments.
PTDoVerb (verb, subject)
Run a single-subject verb action in the verb thread. This will asynchronously run the callback set by PTOnVerb. Ideally your game's input code would call this - so e.g. on a mouseDown event, if your game's UI had the "look" verb enabled, you could fetch the current moused-over object ID and make a call like PTDoVerb("look", "pinking shears").

Parameters:

  • verb string Verb to use.
  • subject string Subject of the verb.
PTSetVerbReadyCheck (callback)
Set a callback for determining if the engine can trigger a verb action. This can be useful for e.g. delaying a verb from being triggered until an actor has finished walking to a location.

Parameters:

  • callback function Function body to call.
PTOnVerb2 (verb, subject_a, subject_b, callback[, directional=false])
Set a callback for a two-subject verb action.

Parameters:

  • verb string Verb to use.
  • subject_a string Subject A of the verb.
  • subject_b string Subject B of the verb.
  • callback function Function body to call, with the verb and the two subjects as arguments.
  • directional boolean Whether to invoke this callback only in a single direction; i.e. on PTDoVerb2("verb", "a", "b") but not on PTDoVerb2("verb", "b", "a"). (default false)
PTDoVerb2 (verb, subject_a, subject_b)
Run a two-subject verb action in the verb thread. This will asynchronously run the callback set by PTOnVerb2. Ideally your game's input code would call this - so e.g. on a mouseDown event, if your game's UI had the "give" verb enabled, and an inventory item selected, you could fetch the current moused-over object ID and make a call like PTDoVerb2("give", "pinking shears", "rock wallaby").

Parameters:

  • verb string Verb to use.
  • subject_a string First subject of the verb.
  • subject_b string Second subject of the verb.
PTSetGrabInputOnVerb (enable)
Set whether to grab the user input when a verb callback is run. If enabled, this means calling any verb action with PTDoVerb or PTDoVerb2 will automatically call PTGrabInput at the start and PTReleaseInput at the end. Defaults to true.

Parameters:

  • enable boolean Whether to grab user input.
PTVerbReady ()
Return whether the current queued verb action is ready. If there is a callback set by PTSetVerbReadyCheck, this will return the response from that.

Returns:

    boolean Whether the queued verb action is ready.

Debug

PTSetWalkBoxDebug (val)
Set whether to draw the walkbox of the current room

Parameters:

  • val boolean true if the walk box is to be drawn, false otherwise.
PTSetImageDebug (val)
Set whether to draw the bounding boxes of images.

Parameters:

  • val boolean true if the image bounding boxes are to be drawn, false otherwise.
PTSetDebugConsole (enable[, device=""])
Set whether to enable the debug console.

Parameters:

  • enable boolean true if the debug console is to be enabled, false otherwise.
  • device string The device to attach the console to; e.g. "COM4" (default "")
generated by LDoc 1.5.0 Last updated 2025-09-04 20:22:16