Multipoints.lua
Download v1.0 (for LunaLua v0.5 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.
Installation
Place the file multipoints.lua and the folder multipoints in the LuaScriptsLib folder.
How to use
METHOD 1:
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, method 2 (introduced in v2.1), is easier to implement and does not require NPCs or events (other than the regular midpoint NPC).
1. Place a single SMBX midpoint on the ground in a location separate from the rest of the level. This can be in its own section, or in any point unreachable from playing the level. It is recommended to re-sprite the midpoint so that it is invisible.
2. Re-sprite the Axe NPC as a midpoint. Alternatively, make the Axe NPC invisible, and use a background object re-sprited as a midpoint. Either way, make sure this object disappears when the player makes contact with the checkpoint.
4. 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.
5. 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.
6. Jump into lunadll.lua, and import Multipoints as an API.
7. 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).
8. You should now have a working checkpoint! You can repeat steps 2-7 as many times as you like to create multiple checkpoints!
METHOD 2:
This method uses Lua code to define and control all aspects of the midpoint, aside from the collection of the midpoint itself. It requires a lot less setup than method 1.
1. Place a single SMBX midpoint on the ground in a location separate from the rest of the level. This can be in its own section, or in any point unreachable from playing the level. It is recommended to re-sprite the midpoint so that it is invisible.
2. Jump into lunadll.lua, and import Multipoints as an API.
3. Use the function "addLuaCheckpoint" to create a new functioning midpoint. You must specify the coordinates of the midpoint and the section you should spawn in. You can optionally also specify spawn coordinates and 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).
4. You should now have a working checkpoint! You can repeat steps 2-3 as many times as you like to create multiple checkpoints!
Example
After first creating an event called "GetCheckpoint", there is an Axe, re-sprited to look like a midpoint, that will spawn the player at (-150000,-150000), and an event called "HideCheckpointLayer" that removed the midpoint and its hitbox:
multipoints = loadAPI("multipoints");
multipoints.addCheckpoint("GetCheckpoint", 0, -150000, -150000, "HideCheckpointLayer");
With the second method, the checkpoint can be defined entirely in Lua:
multipoints = loadAPI("multipoints");
multipoints.addLuaCheckpoint(-150000, -150000, 0);
This will create a checkpoint at position (-150000,-150000), in section 0, and will spawn the player at that location.
Documentation
Values
These are variables you can access
| midpointCount | number | The number of checkpoints currently registered with Multipoint. |
|---|---|---|
| IMG_ID | number | The ID of the checkpoint image used by addLuaCheckpoint. By default, this is 156932. |
| IMG_ALPHA | number | The alpha colour of the checkpoint image used by addLuaCheckpoint. By default this is 0xFF00FF. |
| IMG_PATH | string | The path of the checkpoint image used by addLuaCheckpoint. By default this is an absolute path leading to LuaScriptsLib\multipoints\mp.bmp. |
| 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. (NOTE: A noise will always play on the first checkpoint that is collected in a stage, regardless of the value of this variable). |
| 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. (NOTE: The first checkpoint that is collected in a stage will always push the player up to "big" state. This variable will still affect powerups "greater" than this state, but will not leave the player small, regardless of the value of this variable). |
Functions
| Checkpoint.collect | |
|---|---|
| Forces a checkpoint to be collected. If a checkpoint has already been collected, this function does nothing. | nil |
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
| 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). Caution: This function will not reset SMBX midpoint status, so calling this function may cause the player to spawn at the location of the SMBX midpoint (which is normally inaccessible) when they next spawn. | nil |