Tetroid 3

Setting Up Tetroid 3: What You Actually Need to Know Before Starting

Tetroid 3 is a grid-based spatial puzzle engine that builds on the core mechanics of its predecessors while adding layer-based stacking, dynamic difficulty scaling, and a scripting layer for custom puzzle creation. It runs on both standalone desktop and browser environments, though the two handle inputs and asset pipelines slightly differently. The documentation page has a download section at the top, and the installer bundles the runtime, a level editor, and the SDK tools in one package. Download the latest build from the official Tetroid 3 page, then run the installer. During setup you will be asked to choose between a full install (recommended for most users) and a minimal install that skips the example libraries. After installation, launch the Editor from the start menu. The first thing you will see is a blank workspace with a toolbar across the top and a properties panel on the right. Create a new scene, place a few grid tiles from the asset panel, and hit Play to verify the runtime is responding. The project settings window controls render resolution, input polling rate, and physics substeps. Keep the physics substeps at 2 unless you are building precision timing puzzles, because raising it to 4 can introduce noticeable frame pacing variance on mid-range hardware. This is not theoretical—I hit this exact issue when shipping a speedrun leaderboard build and ended up with inconsistent tick sync on lower-end machines. Setting it back to 2 and using a fixed timestep wrapper resolved the problem cleanly.

How the Core Mechanics Work Under the Hood

Tetroid 3 uses a cell-grid system where each cell can hold a state: empty, solid, active piece, or trigger zone. Pieces are defined as tetromino-style shapes with rotation data, mass, and collision masks. The physics loop runs at the configured tick rate, applies gravity, checks for completed rows or layers, and triggers cascade events when lower cells are removed. Unlike older engines that process collisions per-frame, Tetroid 3 batches collision checks per-tick, which means the visual feel can sometimes lag behind the logic if you are pushing high object counts without adjusting the tick rate. The scripting layer uses a Lua-based API called TetroidScript. It is sandboxed by default, which prevents arbitrary system calls but also means you cannot use native file I/O without enabling the unsafe flag in the project settings. The safe sandbox covers 95% of gameplay logic just fine. Common scripts handle score calculation, combo tracking, spawn timers, and zone activation. If you need persistent data across sessions, use the built-in save system rather than rolling your own JSON reader, because the serialization format includes compression and checksum validation that you would otherwise have to maintain yourself. A detail beginners often miss is how the engine handles overlapping trigger zones. Zones do not stack additively by default. Instead, the engine uses a priority hierarchy where only the highest-priority active zone fires its script event. If you need cumulative effects from multiple zones, you have to create a custom handler that tracks zone enter and exit states manually. I wasted about three hours debugging what I thought was a bug before realizing the zone priority system was working exactly as designed.

Level Design Workflow

Create a new level through File > New Scene. Add a ground plane from the primitives menu, then drag in tile prefabs from the library. Use the snap grid feature (turn it on with the magnet icon in the toolbar) to keep placements aligned. The grid size defaults to 32 pixels, which is fine for standard puzzles, but if you are building high-resolution or mobile-optimized levels, switch the grid to 16 or 64 depending on your target tile size. Place triggers by selecting the trigger tool and drawing rectangles over the areas you want to activate. Assign an event script to each trigger in the properties panel. For spawn zones, configure the timer interval and the piece pool. The piece pool lets you weight specific shapes so that harder levels favor less common pieces. This is how you control difficulty curve without making the level artificially long. Testing happens in real time inside the editor. Use the debug overlay (toggle with Ctrl+D) to see collision bounds, trigger zones, and tick rates. This overlay is invaluable during optimization because it shows you exactly where bottlenecks occur. If you see trigger zone outlines bleeding outside their intended area, it usually means you have nested or overlapping zones that need rearranging.

Performance Considerations and Known Limits

Tetroid 3 runs well on modest hardware, but there are hard limits. The maximum active cell count per scene is around 10,000 before the CPU side of the grid solver starts dropping frames on integrated graphics. The GPU side holds up better, but texture atlas paging can cause hitching if you are streaming high-res tile sets without preloading them. Stick to a single texture atlas under 2048x2048 for best results. Networked multiplayer is supported but not trivial to set up. The engine includes a basic relay server template, but latency compensation for real-time piece movement requires client-side prediction and server reconciliation, which the template does not implement fully. If you are building a competitive multiplayer mode, plan to write your own networking layer or use a third-party solution like Nakama or a custom WebSocket handler. The built-in netcode works for casual turn-based modes but will struggle under tight real-time conditions. Export options cover Windows, macOS, Linux, HTML5, Android, and iOS. The HTML5 export is functional but comes with performance penalties due to WebAssembly overhead and browser memory limits. If you target web, keep scene complexity low and avoid heavy particle systems. The iOS export requires Xcode 14 or later and Apple's latest provisioning profiles, and builds can take significantly longer than desktop exports due to the signing pipeline.

Common Mistakes and How to Avoid Them

One frequent mistake is leaving physics substeps at the default high value when targeting mobile. The smoother physics looks on desktop, but on mobile it burns battery and causes thermal throttling, which leads to sudden frame drops mid-level. Always profile on target hardware before shipping. Another common issue is overusing trigger zones. Each active zone consumes CPU cycles every tick. A level with fifty zones running simultaneously will show measurable lag compared to a similar level with ten well-placed zones. Consolidate logic where possible. Instead of five zones checking for piece completion, use one zone with a script that queries the grid state directly. Asset naming conventions matter more than people expect. The editor does not enforce strict naming, but if you name your prefabs inconsistently, the packager will struggle to resolve references during export. Use a simple prefix system like Tile_Ground, Tile_Wall, Piece_I, Trigger_Combo. It saves debugging time later when you are managing a large asset library.

Where to Get Help and Community Resources

The official forums are active but slow-moving for technical support. Bug reports usually get a response within 48 hours if you include a reproducible case and your system specs. The Discord server has a #help channel where power users share scripts and optimization tips. Documentation improvements are tracked on the project GitHub, and pull requests for SDK fixes are generally accepted if they follow the contribution guidelines. If you are new to Tetroid 3, start with the included tutorial levels. They cover spawning, scoring, triggers, and basic scripting. Do not skip them. The UI changed between version 2 and version 3, and many assumptions from the old engine no longer apply. Jumping straight into complex projects without understanding the new pipeline will cost you more time than it saves. The download link is available on the official Tetroid 3 website. Community forks and third-party templates exist on GitHub, but stick to official releases for stability unless you have a specific reason to modify the engine source. The SDK license allows modification, but distributing modified builds requires proper attribution under the terms.