This is the documentation for the subsection of Triangle.js that simulates the TETR.IO core game engine. For the full documentation, see the main README.
An Engine is the wrapper class that handles an individual player's game. It takes in an EngineInitializeParams, which are saved to the Engine's initializer property.
An Engine's state is made up of several different components, such as the falling piece state, garbage queue, and more. To save an Engine's state, use the engine.snapshot() method. Then, you can restore the state using engine.fromSnapshot(<snapshot>) method.
The following is an example of how you would create a clone of an engine:
// assume `engine` has already been delared as an `Engine`
const newEngine = new Engine(engine.initializer);
newEngine.fromSnapshot(engine.snapshot());
An Engine has the events property, which functions very similarly to the Node EventEmitter class. You can view the list of events here.
There are two main ways to manipulate state: using using the engine.press(<key>) function or by passing frames into the engine.tick(<frames>) function.
engine.press(<key>) performs the key press passed into the function. For example, running engine.press("moveRight") moves the falling piece 1 square right. There are also two non-standard keys (not valid for passing into engine.tick): dasLeft and dasRight.
The function returns a LockRes if the move is hardDrop. Otherwise, it returns true if the move altered the falling piece position or rotation, and false if it did not.
engine.tick(type ige, keydown, or keyup.
When using engine.press on the engine controlled by the Game class, you must either save a snapshot before manipulating the state (recommended) or clone the engine before manipulating the state. Otherwise, the Game's state will desync from the server's state.
The Engine's queue is available through the engine.queue property. It is an instance of the Queue class, which is a wrapper around the TETR.IO queue system. You may freely set engine.queue.minLength, which is the minimum number of pieces that must be in the queue. The queue will automatically refill to this length when it is below it.
The Engine's garbage queue is available through the engine.garbageQueue property. It is an instance of the GarbageQueue class, which is a wrapper around the TETR.IO garbage queue system.
The full size of the garbage queue can be accessed through engine.garbageQueue.size. You can also access the current garbage queue through engine.garbageQueue.queue, which is an array of IncomingGarbage objects.
An IncomingGarbage will become tankable when the following is true:
item.frame + this.options.garbage.speed <= frame;
Where item is the IncomingGarbage object, this is the GarbageQueue instance, and frame is the current game frame.
The Engine's board is available through the engine.board property. It is an instance of the Board class. The board has a 4 key properties:
board.width: The width of the board.board.height: The height of the board.board.fullHeight: The full height of the board, which is the height of the board plus the board buffer.board.state: The 2D array (array of rows) of the board state, where each element is a BoardSquare. The 0th row is at the bottom of the board, and the last row is at the top of the board.The Engine's falling piece is available through the engine.falling property. It is an instance of the Tetromino class. A Tetromino instance has a few important properties:
tetromino.symbol: One of Mino.I, Mino.J, Mino.L, Mino.O, Mino.S, Mino.T, or Mino.Z.tetromino.x: The x position of the tetromino on the board. This is the same as tetromino.location[0].tetromino.y: The y position of the tetromino on the board, rounded down to the nearest integer. This is NOT the same as tetromino.location[1], which is a float.tetromino.rotation: The Rotation of the tetromino, which one of 0, 1, 2, or 3. Setting Rotation will normalize the rotation to the range of 0 to 3, but will not perform kicks or boundary checks.tetromino.location: The location of the tetromino on the board, which is an array of [x, y] where x is the x position and y is the y position. [0, 0] is the bottom left corner of the board.