This library is not officially supported nor endorsed by TETR.IO. Use of the main game API is only permitted with an official bot account. You assume all responsibility for any actions that result in staff action (warnings/bans, etc). The main game API is not documented and this library may break at any time. This restriction includes the use of the
Client
class and theAPI
class.
The Tetra Channel section of this library (imported through
@haelp/teto/ch
) and the Engine (imported through@haelp/teto/engine
) is open to use by anyone.
Triangle.js was last known to work with TETR.IO Beta version 1.7.3.
npm i @haelp/teto
or
git clone https://github.com/halp1/triangle triangle
Note: Only looking to use the
ch.tetr.io
api? Check out the documentation here.
It is highly recommended that you use a Typescript project for this library if you choose to clone from source. If you are not using Typescript, you will need to use a tool like tsc
to compile the source code. This is because the TETR.IO api is complex and being able to use type checking will greatly reduce the chance of errors. Incorrectly formatted messages sent to the server may cause an account ban.
It is also recommended (but not required) that you add a typescript path mapping to the src
directory in your tsconfig.json
file. This will allow you to import the library like so:
import { Client } from "@triangle";
To do this, add the following to the "compilerOptions" object in your tsconfig.json
file:
"paths": {
"@triangle": ["./path/to/triangle/src"]
}
The following usage examples assume you are using Typescript. They also assume you can use top level await. If you cannot, you will need to wrap the code in an async function.
Warning: Use the latest LTS versoin when using Node.js with Triangle.js. Triangle.js was last known to work with Node.js 22.x.
Warning: Triangle.js uses Node.js/Bun's built-in WebSocket client. If you have to use Node.js <
v22.4.0
, use thews
package as a pollyfill:globalThis.WebSocket = require("ws").WebSocket;
Tip: When using Node.js, add the
--enable-source-maps
flag to your node command to get better stack traces.
Node.js:
import { Client } from "@haelp/teto";
const client = await Client.connect({
username: "your-username",
password: "your-password"
});
// or {token: "your-token"}
const room = await client.rooms.create("private");
console.log("Joined room", room.id);
const rooms = await client.rooms.list();
const room = await client.rooms.join(rooms[0].id);
console.log("Joined room", room.id);
The following example presses the hard drop key every 1/2 second
room.start();
const [tick, engine] = await client.wait("client.game.round.start");
tick(async (data) => {
if (data.frame % 30 === 29) {
return {
keys: [
{
frame: data.frame,
type: "keydown",
data: {
key: "hardDrop",
subframe: 0
}
},
{
frame: data.frame,
type: "keyup",
data: {
key: "hardDrop",
subframe: 0
}
}
]
};
}
return {};
});
await client.wait("game.end");
console.log("game over");
View more gameplay documentation here and here.
room.chat("Hello, world!");
// send a pinned message (when host)
room.chat("Hello, world!", true);
client.on("room.chat", (data) => {
console.log(data.user, "says", data.content);
});
The Triangle.js client follows an async/await based method, while TETR.IO generally has a event/callback based system. To help facilitate the connection between these two systems, the client provides several helper methods.
All of these methods are typed, so your ide will likely assist with autocomplete. All events are in src/types/events
client.emit
- Takes in an event (sent as "command" to TETR.IO) and optionally a data parameter (sent as "data")
client.emit(<event>, <data>);
client.wait
- Waits for an event to occur and returns a promise of the data in the event.
const data = await client.wait(<event>);
client.wrap
- Sends an event and waits for a return event. Throws an error if the server responds with an "err" message while waiting.
const data = await client.wrap(<send event>, <data>, <receive event>);
For events that you might want to handle multiple times, you can use client.on
, client.off
, and client.once
(node EventEmitter methods).
Client events are not sent by TETR.IO. They are events sent by the Triangle.js client itself, to help make creating a bot easier.
For example the client.room.players
event fires every time a player moves their bracket, joins, or leaves. Rather than listening to several events and managing a players list yourself (with room.player.add
, room.player.remove
, room.update
, room.update.bracket
, etc) you can use the single client.room.players
. See src/types/events/in/client for more events you can use.
Please see the troubleshooting guide.
The code should only be used on an authorized bot account (or you risk being banned).
It is recommended to set a custom userAgent
in the client options to identify your bot to the server.
Be careful with what variables you save and where. Due to the event-based nature of TETR.IO and this library, it is easy to accidentally create a memory leak. For example, the "tick" function exposed on the "client.game.start" event is used for this reason.
Install bun if you haven't already:
curl -fsSL https://bun.sh/install | bash
Then run:
bun run build
File an issue and make a pull request on Github.
Made by halp (website under construction)
Thanks to luke and redstone576 for testing this library.
Enjoying Triangle.js? Leave a star!
Interested in contributing to the project? Contact haelp
on Discord (Please come with some experience with TETR.IO API and an understanding of this library).