Multipoints.lua

*Obsoleted by NPC-400, NPC-430 and the "Checkpoint" class in SMBX2 B4+

Download v2.2 (for LunaLua v0.6 or below)

Multipoints is a library that enhances SMBX midpoints. It allows for multiple midpoints to be placed in a level, and for the player to spawn at a different location to the midpoint itself. It can also expand midpoints in other ways, though these are more advanced.

IMPORTANT: Multipoints 3.0.1 and below will NOT work in a packaged game in LunaLua v0.7.1.1 due to a bug in LunaLua

Installation

Drop the file "multipoints.lua" and the folder named "multipoints" into the LuaScriptsLib folder in your SMBX installation. Multipoints should now be installed!

How to Use

1. Find where you want to place your checkpoint, and keep track of the coordinates.

2. Import the Multipoints API using the code: local multipoints = API.load("multipoints")

3. Use the function "multipoints.addLuaCheckpoint" to create your checkpoint. Pass the coordinates you found in step 1 to place the checkpoints, and fill in the section to spawn in. Optionally, you can specify spawn coordinates that differ from the checkpoint's position, and add a list of Lua function to call when spawning to the checkpoint (this is particularly useful if your Lua program changes state as you progress through the level).

4. You should now have a working checkpoint! You can repeat steps 1-3 as many times as you like to create multiple checkpoints!

Alternative method

The original setup of multipoints required the use of NPCs and events to create checkpoints. This has been kept for compatibility reasons but the newer method introduced in v2.1 is easier to implement and does not require NPCs or events. This alternative method also has some restricted functionality where multiple players are involved.

1. Re-sprite the Axe NPC as a checkpoint. Alternatively, make the Axe NPC invisible, and use a background object re-sprited as a checkpoint. Either way, make sure this object disappears when the player makes contact with the checkpoint.

2. Make the checkpoint Axe call a SMBX event on Death. This event does not need to do anything in SMBX, but make a note of the name. Here, it will be referred to as "GetCheckpoint", but any name will work.

3. Make a layer that hides the Multipoint checkpoint and its hitbox. This will be used when we spawn having already collected the checkpoint. Here, it will be referred to as "HideCheckpointLayer", but any name will work.

4. Jump into lunadll.lua, and import Multipoints as an API (see step 2 in the regular method).

5. Use the function "addCheckpoint" to create a new functioning checkpoint. You must specify the name of the "GetCheckpoint" event, the section containing the Multipoint checkpoint, the spawn location, and the name of the "HideCheckpointLayer" event. You can optionally also specify a list of Lua functions to call when spawning to that checkpoint (this is particularly useful if your Lua program changes state as you progress through the level).

6. You should now have a working checkpoint! You can repeat steps 1-5 as many times as you like to create multiple checkpoints!

Example

This will create a checkpoint at (-150000,-150000), and will spawn the player at that location.

local multipoints = API.load("multipoints");

multipoints.addLuaCheckpoint(-150000, -150000, 0);

Documentation

Values

These are variables you can access

midpointCount	number	The number of checkpoints currently registered with Multipoints.
IMG	LuaImageResource	The checkpoint image used by addLuaCheckpoint. By default, this is the .png image in the multipoints folder.
IMG_PATH	string	The path of the checkpoint image used by addLuaCheckpoint. By default this is an absolute path leading to LuaScriptsLib\multipoints\mp.png.
IMG_SIZE	table	A table with two elements: width and height. This should be set to the same size as the graphic at IMG_PATH.

Classes

These are classes contained within this library

Checkpoint

Values

Checkpoint.x	number	For a Lua checkpoint, this is the x coordinate of the checkpoint object. For a standard checkpoint, this will always be 0.
Checkpoint.y	number	For a Lua checkpoint, this is the x coordinate of the checkpoint object. For a standard checkpoint, this will always be 0.
Checkpoint.collected	boolean:read-only	A read-only variable that is true if the checkpoint has been collected.
Checkpoint.silent	boolean	If this is true, the checkpoint will attempt to not make a noise when collected.
Checkpoint.visible	boolean	Should the checkpoint be visible and collectible in the stage? For a standard checkpoint, this will always be true.
Checkpoint.power	number	The power the player should be pushed up to when collecting this checkpoint. By default, this is 2 (big). Set this to 0 to leave the player's powerup unchanged.

Functions

Checkpoint.collect		player
Forces a checkpoint to be collected. If a checkpoint has already been collected, this function does nothing. Optionally, a "player" can be specified, which will power up that specific player.	nil	Player:optional The player to power up when collecting the checkpoint. If set to nil or left out, all players will be powered up.

External Use Functions

These are functions you will need to use the library

addCheckpoint		getEvent	section	spawnX	spawnY	hideEvent	extraActions
Creates a new checkpoint.	Checkpoint	string The name of the SMBX event called when the checkpoint is collected.	number The section in which to spawn the player.	number The X coordinate at which to spawn the player.	number The Y coordinate at which to spawn the player.	string:optional The SMBX event to trigger when respawning after having collected this checkpoint. This typically hides the checkpoint layer, so it cannot be collected again.	function:optional Lua code to run when respawning on this midpoint.
addLuaCheckpoint		x	y	section	spawnX	spawnY	extraActions
Creates a new checkpoint.	Checkpoint	number The X coordinate of the checkpoint.	number The Y coordinate of the checkpoint.	number The section in which to spawn the player.	number:optional The X coordinate at which to spawn the player.	number:optional The Y coordinate at which to spawn the player.	function:optional Lua code to run when respawning on this midpoint.
setImage		path	id	alpha
Reloads the checkpoint image used by addLuaCheckpoint. When called with less than 3 arguments, it uses the values in IMG_ID, IMG_ALPHA and IMG_PATH, and otherwise sets those values.	nil	string:optional The path of the checkpoint sprite.	number:optional The ID of the loaded image.	number:optional The transparency colour of the image.

Internal Use Functions

These are functions that the library uses to function, but are not necessary for the user


getCheckpoint		id
Returns the checkpoint object given by the specified ID. If no checkpoint with the given ID has been defined, returns nil.	Checkpoint	number The id of the checkpoint to get.
getCheckpointID
Returns the ID of the last collected checkpoint. Returns -1 if no checkpoint has yet been collected.	number

getCheckpointStatus		id
Returns true if the specified checkpoint has been collected, false otherwise.	boolean	number The ID of the checkpoint.

resetMidpoints
Resets the midpoint values to their defaults. This effectively sets all midpoints to their uncollected state (but won't re-spawn collected midpoints).	nil

Events

These are events you can define in your lunadll.lua file that will be called by the library. The self argument should not be included in the function definition, and will automatically be assigned to the "self" variable.

multipoints:onCollected	self	id
Called when a checkpoint is collected.	Checkpoint The checkpoint object that was collected.	number The id of the checkpoint that was collected.
multipoints.onLevelStart
Called on the first frame of a level, just after multipoints has spawned the player and called any extra functions. NOTE: This is NOT guaranteed to run before onLoop, so if you use it for initialisation, keep that in mind.