Elevator Tutorial
=================
What this is
------------
This explains how the elevator script works.
The elevator code is now split into:
Elevator.asc
Elevator.mut
Elevator.asc contains the elevator behavior.
Elevator.mut contains admin commands and the Elevator Editor.
Open the editor with:
!elevatorEdit
or:
!elevatorEditor
The basic idea
--------------
An elevator is made from event tiles.
The script looks for these events:
Pink Platform
Boll Platform
If the event has elevator parameters, the script turns it into an elevator
piece.
The visible tile from layer 4 is removed from the map and then drawn by the
elevator object while it moves.
This is why an elevator can look like a normal tile, wall, platform, floor,
or room piece.
Pink Platform elevators vs Boll Platform elevators
--------------------------------------------------
Both Pink Platform and Boll Platform can become elevator pieces.
The important difference is this:
Pink Platform can be used for normal automatic elevators.
Boll Platform is excluded from the automatic up/down movement code.
So in practice:
Use Pink Platform for:
- controllable elevators
- autonomous elevators
- normal elevator pieces
Use Boll Platform only when:
- you specifically want a platform object that uses the elevator behavior,
- but should not be driven by the automatic elevator movement code.
For beginner mapping, use Pink Platform.
If you make a Boll Platform elevator with autonomous settings, it may
activate like an elevator piece, but the automatic movement code will not
move it the same way as a Pink Platform elevator.
Elevator ids
------------
Every elevator has an id.
All pieces with the same id belong to the same elevator.
Example:
Elevator 1:
blue platform tile
yellow wall tile
yellow ceiling tile
red limit tile
All of those should use elevator id 1.
Another elevator should use another id:
Elevator 2:
green platform tile
yellow side wall tile
red limit tile
The 7 editor blocks
-------------------
The Elevator Editor has seven block tools.
Blue block - controllable elevator
This transforms a tile into an elevator that can be controlled by up / down
player keys.
Green block - autonomous elevator
This transforms a tile into an autonomous elevator that moves by itself
when the player gets on top of the tile.
Yellow block - elevator components
This transforms a tile into a component of that elevator.
It moves with the elevator and is solid.
It should not be the main trigger tile.
Use this for:
- walls
- ceiling
- floor decorations
- an elevator room
Yellow outline block - background components
This transforms a tile into a background component of that elevator.
It moves with the elevator, but it is not solid.
Use this for background tiles or decorative room pieces.
Purple block - Boll Platform elevator piece
This places a Boll Platform elevator piece.
It moves with the elevator id, but it should not be used as the normal
autonomous trigger tile.
Red block - elevator limit
This places the upward limit that an elevator can reach.
White outline block - delete tile
This deletes an elevator tile or elevator limit from the clicked tile.
It deletes one tile at a time.
The Delete button still deletes the whole selected elevator id.
Controllable elevators
----------------------
A controllable elevator is controlled by the player standing on it.
Use:
Blue block - controllable elevator
When the player stands on it:
Up moves the elevator up.
Down moves the elevator down.
Left and Right can move it sideways if the elevator is allowed to move
horizontally.
Fire locks or unlocks it.
Jump releases control.
Beginner example:
1. Open !elevatorEdit.
2. Select elevator < 1 >.
3. Click the blue block.
4. Click a tile at the start of the level.
5. Click the red block.
6. Click a tile above the elevator.
Now elevator 1 has:
- one controllable elevator tile
- one upward limit
Autonomous elevators
--------------------
An autonomous elevator moves by itself when the player steps on it.
Use:
Green block - autonomous elevator
The player does not press up or down to control it.
The elevator decides whether to go up or down based on its internal up/down
state.
Beginner example:
1. Select elevator < 2 >.
2. Click the green block.
3. Click the platform tile.
4. Click the red block.
5. Click a tile above the platform.
Now elevator 2 has:
- one autonomous platform tile
- one upward limit
Elevator components
-------------------
An elevator component is a tile that belongs to the elevator but is not
meant to trigger movement.
Use:
Yellow block - elevator components
Components are useful when you want more than a single platform.
Example elevator room:
YYY
YBY
YYY
Where:
B = blue controllable elevator tile
Y = yellow component tile
The blue tile is the control tile.
The yellow tiles move with it.
Another example:
YYY
YGY
YYY
Where:
G = green autonomous elevator tile
Y = yellow component tile
The green tile triggers autonomous movement.
The yellow tiles are just part of the elevator room.
Elevator limits
---------------
Use:
Red block - elevator limit
The red limit tells the script how high the elevator can go.
In JJ2, smaller Y numbers are higher on the map.
So if your elevator starts at tile Y = 60 and the limit is at tile Y = 50,
the elevator can go upward until it reaches that area.
Beginner example:
Start platform:
x = 20, y = 60
Red limit:
x = 20, y = 50
The elevator can move upward about 10 tiles.
Important parameters
--------------------
The elevator script reads these event parameters:
Parameter 0, length 2:
foreground
Values:
0 = solid elevator piece
1 = background / non-platform elevator piece
Most beginner elevator pieces should use 0.
Parameter 2, length -6:
speed
Values:
-1 or lower = not an elevator
0 = elevator component / no movement speed
1 or higher = moving elevator speed
The editor uses:
1 for blue and green blocks
0 for yellow component blocks
0 for yellow outline background component blocks
0 for purple Boll Platform pieces
Parameter 8, length 4:
elevator id
Values:
0 = not an elevator
1 to 15 = elevator id
All pieces with the same id move together.
Parameter 12, length 1:
controllable
Values:
0 = autonomous elevator
1 = controllable elevator
The editor uses:
1 for blue blocks
0 for green blocks
0 for yellow blocks
0 for yellow outline blocks
How the editor maps to parameters
---------------------------------
Blue block - controllable elevator:
Event: Pink Platform
foreground = 0
speed = 1
elevator id = selected elevator number
controllable = 1
Green block - autonomous elevator:
Event: Pink Platform
foreground = 0
speed = 1
elevator id = selected elevator number
controllable = 0
Yellow block - elevator component:
Event: Pink Platform
foreground = 0
speed = 0
elevator id = selected elevator number
controllable = 0
Yellow outline block - background component:
Event: Pink Platform
foreground = 1
speed = 0
elevator id = selected elevator number
controllable = 0
Purple block - Boll Platform elevator piece:
Event: Boll Platform
foreground = 0
speed = 0
elevator id = selected elevator number
controllable = 0
Red block - elevator limit:
Event: Thing
elevator id = selected elevator number
White outline block - delete tile:
Removes the event from the clicked elevator tile or limit tile.
Marks the changed layout as unsaved.
Manual event setup example
--------------------------
If you are editing events by hand, a controllable elevator tile looks like
this:
Event:
Pink Platform
Parameters:
foreground = 0
speed = 1
elevator id = 1
controllable = 1
An autonomous elevator tile:
Event:
Pink Platform
Parameters:
foreground = 0
speed = 1
elevator id = 2
controllable = 0
A component tile:
Event:
Pink Platform
Parameters:
foreground = 0
speed = 0
elevator id = 2
controllable = 0
A Boll Platform elevator piece:
Event:
Boll Platform
Parameters:
foreground = 0
speed = 0
elevator id = 2
controllable = 0
A limit tile:
Event:
Thing
Parameters:
elevator id = 2
Two simple elevator examples
----------------------------
Example 1: controllable elevator
Selected elevator:
< 1 >
Place:
Blue block at the elevator floor.
Red block above it.
Result:
Player stands on the blue block and controls it with up/down.
Example 2: autonomous elevator with a room
Selected elevator:
< 2 >
Place:
Green block at the main platform.
Yellow blocks around it for walls/ceiling.
Red block above it.
Result:
Player stands on the green block.
The whole elevator room moves.
Yellow pieces move with it but are not the main trigger.
Admin commands
--------------
The mutator keeps these admin commands:
!elevator up <id>
!elevator climb <id>
!elevator down <id>
!elevator descend <id>
!elevator lock <id>
!elevator stop <id>
!elevator fup <id>
!elevator fdown <id>
!elevator location <id>
Examples:
!elevator up 1
!elevator down 1
!elevator lock 1
!elevator fup 1
!elevator location 1
Meaning:
up / climb:
Move the elevator up.
down / descend:
Move the elevator down.
lock / stop:
Toggle locked state.
fup:
Force unlock, then move up.
fdown:
Force unlock, then move down.
location:
Show the location of the bottom piece.
Common mistakes
---------------
Mistake:
Using elevator id 0.
Fix:
Use id 1 or higher.
Mistake:
Putting different parts of the same elevator on different ids.
Fix:
All pieces of one elevator must use the same id.
Mistake:
Forgetting the red limit.
Fix:
Place a red limit above the elevator.
Mistake:
Using only yellow components.
Fix:
Use at least one blue or green block as the main elevator tile.
Mistake:
Expecting a Boll Platform autonomous elevator to behave like a Pink
Platform autonomous elevator.
Fix:
Use Pink Platform for normal autonomous elevators.
Notes about saving
------------------
The editor does not change the running level immediately.
While the editor is open, it draws colored overlays on top of the real
level tiles.
The real tiles stay visible, so you can still see the elevator room you are
designing.
After placing or deleting elevator tiles, press:
Save
Save writes the current elevator event layout into this file:
levelName_Elevator.asdat
For example:
ultra hotel 2_Elevator.asdat
When the level loads, Elevator.asc looks for that file.
If the file exists:
1. The script clears the level's current elevator events.
2. The script rebuilds the elevator events from levelName_Elevator.asdat.
3. The elevator behavior starts using those saved events.
This means deleted original elevators stay deleted after reload, because
the saved .asdat file becomes the elevator layout used by the script.
Important:
Save does not make the elevator move immediately in the current game
session.
Reload the level to apply the saved elevator layout.
If you close the editor with unsaved changes, it saves automatically.
