9.9 KiB
MATRIX
A rectangular grid of cells with a small built-in stone-falling physics system and primitive enemy pathfinding. Designed around a single use case — the digging minigame (Kretes sections in Reksio i Ufo: the wall on Indor and the prison-tunnel on Kuran).
Grid data lives in a one-dimensional array of integers — a cell's address is computed as index = y * width + x. Hence the family of methods that converts between linear index and 2D position.
Field codes
Values used by GET, GETCELLSNO, SET, SETROW and the internal physics system:
| Code | Meaning |
|---|---|
0 |
empty cell |
1 |
ground |
2 |
stone |
3 |
dynamite stick |
4 |
weak (destructible) wall |
5 |
enemy |
6 |
strong (indestructible) wall |
7 |
lit dynamite stick |
8 |
cell within blast radius |
9 |
exit |
99 |
Kretes' position |
Movement direction codes
Values used by TICK, NEXT, and CALCENEMYMOVEDIR:
| Code | Direction |
|---|---|
0 |
left |
1 |
up |
2 |
right |
3 |
down |
The physics system uses additional codes returned by TICK and consumed by NEXT:
| Code | Operation |
|---|---|
1 |
stone falls down |
2 |
stone slides diagonally to the left |
3 |
stone slides diagonally to the right |
4 |
stone collides with an enemy and explodes |
Fields
BASEPOS
INTEGER, INTEGER BASEPOS
Pixel position of the grid's top-left corner on screen (X,Y).
CELLHEIGHT
INTEGER CELLHEIGHT
Height of a single cell in pixels.
CELLWIDTH
INTEGER CELLWIDTH
Width of a single cell in pixels.
SIZE
INTEGER, INTEGER SIZE
Grid dimensions in cells (width,height). The value also dictates the size of the internal field-code array.
Methods
CALCENEMYMOVEDEST
INTEGER CALCENEMYMOVEDEST(INTEGER oldCell, INTEGER direction)
Computes the destination cell for an enemy moving from oldCell in the given direction. If the target cell is out of bounds or not empty, oldCell is returned unchanged.
Parameters
oldCell— the enemy's current cell index.direction— movement direction (0–3, see Movement direction codes).
Returns: INTEGER — destination cell index.
Examples
MAT^CALCENEMYMOVEDEST(IENOLDCELL,IENNEWDIR);
CALCENEMYMOVEDIR
INTEGER CALCENEMYMOVEDIR(INTEGER oldCell, INTEGER oldDir)
Computes the next movement direction for an enemy. The algorithm prefers turning left: it first checks (oldDir+3) MOD 4, then oldDir, then right, and finally backwards. The first direction whose target cell is empty is returned; if none is available, the leftward direction is returned anyway.
Parameters
oldCell— the enemy's current cell index.oldDir— the previous-step movement direction.
Returns: INTEGER — the new movement direction.
Examples
MAT^CALCENEMYMOVEDIR(IENOLDCELL,IENOLDDIR);
CANHEROGOTO
BOOL CANHEROGOTO(INTEGER cellNo)
Checks whether the protagonist can step onto the given cell. A cell is walkable if it does not contain a weak wall, strong wall, enemy or stone, and is not part of a gate area set with SETGATE.
Parameters
cellNo— index of the cell to check.
Returns: BOOL — TRUE if the cell is walkable.
Examples
MAT^CANHEROGOTO(I_0);
GET
INTEGER GET(INTEGER cellNo)
Returns the field code of the cell at the given index. For out-of-range indices returns 0.
Parameters
cellNo— cell index.
Returns: INTEGER — field code (see Field codes).
Examples
MAT^GET(I_ITERATOR);
MAT^GET(I_MOLE_FIELD_CURR);
GETCELLOFFSET
INTEGER GETCELLOFFSET(INTEGER x, INTEGER y)
Returns the cell index for the given (x, y) grid coordinates. Returns -1 if the coordinates fall outside the grid.
Parameters
x,y— grid coordinates.
Returns: INTEGER — the cell index or -1.
Examples
MAT^GETCELLOFFSET(ISSRCX,ISSRCY);
MAT^GETCELLOFFSET(ISTRGX,ISTRGY);
GETCELLPOSX
INTEGER GETCELLPOSX(INTEGER cellNo)
Returns the cell's X position in pixels (BASEPOS.X + col * CELLWIDTH).
Parameters
cellNo— cell index.
Returns: INTEGER — X coordinate in pixels.
GETCELLPOSY
INTEGER GETCELLPOSY(INTEGER cellNo)
Returns the cell's Y position in pixels (BASEPOS.Y + row * CELLHEIGHT).
Parameters
cellNo— cell index.
Returns: INTEGER — Y coordinate in pixels.
GETCELLSNO
INTEGER GETCELLSNO(INTEGER cellCode)
Returns the number of cells with the given field code.
Parameters
cellCode— the field code to count.
Returns: INTEGER — number of matching cells.
Examples
MAT^GETCELLSNO(IC_FIELD_CODE_EXIT);
MAT^GETCELLSNO(IC_FIELD_CODE_ENEMY);
GETFIELDPOSX
INTEGER GETFIELDPOSX(INTEGER cellNo)
Alias of GETCELLPOSX, used in Reksio i Ufo with the Piklib 7.1 engine. Piklib 8 no longer ships this method — calling it crashes the engine.
Parameters
cellNo— cell index.
Returns: INTEGER — X coordinate in pixels.
GETFIELDPOSY
INTEGER GETFIELDPOSY(INTEGER cellNo)
Alias of GETCELLPOSY, used in Reksio i Ufo with the Piklib 7.1 engine. Piklib 8 no longer ships this method — calling it crashes the engine.
Parameters
cellNo— cell index.
Returns: INTEGER — Y coordinate in pixels.
GETOFFSET
INTEGER GETOFFSET(INTEGER x, INTEGER y)
Alias of GETCELLOFFSET, used in Reksio i Ufo with the Piklib 7.1 engine. Piklib 8 replaces it with GETCELLOFFSET.
Parameters
x,y— grid coordinates.
Returns: INTEGER — cell index or -1.
ISGATEEMPTY
BOOL ISGATEEMPTY()
Checks whether all cells in the gate area set with SETGATE have field code 0 (empty). Returns FALSE if no gate has been set.
Returns: BOOL — TRUE if all gate cells are empty.
Examples
MAT^ISGATEEMPTY();
ISINGATE
BOOL ISINGATE(INTEGER cellNo)
Checks whether the cell at the given index belongs to the gate area set with SETGATE.
Parameters
cellNo— cell index.
Returns: BOOL — TRUE if the cell is inside the gate area.
MOVE
void MOVE(INTEGER oldCell, INTEGER newCell)
Moves the contents of the source cell to the destination cell; the source cell becomes empty (code 0).
Parameters
oldCell— source cell index.newCell— destination cell index.
Examples
MAT^MOVE(I_0,I_1);
NEXT
INTEGER NEXT()
Executes the next queued move generated by TICK. The source cell is cleared and the destination cell receives the stone code. After the move the ONNEXT signal is emitted for every move except the last one in the queue, which fires ONLATEST instead.
Returns: INTEGER — 0 if the queue is empty; 1 for an ordinary stone move; 2 if the stone has come to rest two cells above Kretes (collision).
Examples
MAT^NEXT();
SET
void SET(INTEGER cellNo, INTEGER cellCode)
void SET(INTEGER x, INTEGER y, INTEGER cellCode)
Sets a cell's field code. Two forms are accepted: the first takes a precomputed cell index, the second takes (x, y) coordinates.
Parameters
cellNo— cell index (form 1).x,y— cell coordinates (form 2).cellCode— new field code (see Field codes).
Examples
MAT^SET(I_MOLE_FIELD_CURR,IC_FIELD_CODE_EMPTY);
MAT^SET([I_FIELD_INDEX%I_LEVEL_WIDTH],[I_FIELD_INDEX@I_LEVEL_WIDTH],IC_FIELD_CODE_EMPTY);
SETGATE
void SETGATE(INTEGER startX, INTEGER startY, INTEGER endX, INTEGER endY)
Defines a rectangular gate area, inclusive of both corners. The gate affects CANHEROGOTO, ISGATEEMPTY, and ISINGATE.
Parameters
startX,startY— coordinates of the gate's top-left corner.endX,endY— coordinates of the gate's bottom-right corner.
Examples
MAT^SETGATE(3,1,16,4);
SETROW
void SETROW(INTEGER row, INTEGER cellCode1, [INTEGER cellCode2, ...])
Sets field codes for all cells in the given row, starting from column 0. Excess arguments (beyond the grid's width) are ignored.
Parameters
row— row index.cellCode1,cellCode2, … — field codes for successive cells in the row.
Examples
MAT^SETROW(0,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6,6);
MAT^SETROW(1,6,6,6,2,2,2,2,2,2,2,2,2,2,2,2,2,2,6,6,6);
TICK
void TICK()
Executes one physics tick. The grid is scanned bottom-to-top, left-to-right. For each stone the following cases are checked in order:
- Is the cell directly below empty — schedule a downward move.
- Is the cell below an enemy — schedule an explosion.
- Are the diagonally adjacent cells (and the lateral neighbour) empty — schedule a diagonal slide.
Scheduled moves are appended to an internal queue and executed one-by-one by NEXT. Each entry records the source cell's X and Y, plus the operation code.
Examples
MAT^TICK();
Signals
ONINIT
Fired when the object is initialised.
ONNEXT
Fired by NEXT after a move that was not the last in the current queue. Signal arguments are the source cell's X ($1), Y ($2) and operation code ($3).
ONLATEST
Fired by NEXT after the last queued move. Arguments are identical to ONNEXT.
ONSIGNAL
Fired when a signal arrives (see Events and signals).