Getting Started

Tecs2D is a 2D game engine built on top of Tecs and Love2D 12. It wires the ECS into the Love2D event loop and adds rendering, audio, input, physics, tiled maps, tweens, and dev tooling.

The fastest way to start is the starter template.

Prerequisites

You will need to install these tools to use Tecs2D:

• Lua: Runs the starter build script
• LuaRocks: Lua package manager - Installation
• Teal: Typed Lua compiler - Download
• LÖVE 12: Game runtime. LÖVE 12 is not yet a stable release, so Tecs2D targets nightly builds. The starter downloads this automatically.

Next, install Tecs2D (and Tecs) into your project using a single command:

luarocks install --dev --tree=src/vendor --lua-version=5.1 tecs2d

While Tecs2D is in preview, --dev is required. There are no tagged releases yet.

Starter template

Git Clone

git clone https://github.com/tecs-dev/tecs-starter.git my-game
cd my-game
./tecs run

GitHub CLI

gh repo create my-game --template tecs-dev/tecs-starter --clone
cd my-game
./tecs run

You should see the scrolling shooter demo.

What's included

The starter template comes pre-configured with:

• tecs CLI - Cross-platform setup, checking, builds, asset copying, dependency management, and launching
• tlconfig.lua - Teal compiler configuration
• Type definitions - Downloaded automatically for Love2D, LuaJIT FFI, etc.
• Demo game - A small fixed-camera scrolling shooter built from focused plugins and state systems

Project structure

my-game/
├── tecs                  # Cross-platform build orchestration
├── tlconfig.lua          # Teal configuration
├── src/
│   ├── main.tl           # Game entry point
│   ├── conf.tl           # Love2D configuration
│   └── plugins/
│       ├── game.tl       # Game setup and shared systems
│       ├── shared.tl     # Components, constants, and asset preload
│       └── states/       # Focused state/gameplay plugins
├── assets/               # Images, sounds, fonts
├── types/                # Type definitions (generated)
├── build/                # Compiled output (generated)
└── src/vendor/           # Dependencies (generated)

Wiring up Tecs2D

tecs2d.run configures the world, render pipeline, and game plugin, then takes over Love2D's main loop:

local tecs <const> = require("tecs")
local tecs2d <const> = require("tecs2d")

local function game(world: tecs.World)
    -- register components, spawn entities, add systems
end

love.run = tecs2d.run({
    fps = 60,
    game = game,
    render = {
        virtualWidth = 800,
        virtualHeight = 600,
    },
})

The pure-ECS pieces (World, components, queries, systems) come from Tecs. Tecs2D adds the engine layer: rendering, audio, input, etc. Install tecs2d when you want the full engine layer; it depends on tecs automatically.

Build targets

Command	Description
./tecs run	Build and run the game (runs setup automatically)
./tecs build	Compile without running
./tecs check	Typecheck without compiling
./tecs clean	Remove build artifacts
./tecs love12	Download or refresh the local Love2D 12 runtime

On Windows, use lua tecs <target> instead of ./tecs <target>.

Managing dependencies

# Add a package
luarocks install --tree=src/vendor --lua-version=5.1 penlight

# Add a specific version
luarocks install --tree=src/vendor --lua-version=5.1 penlight 1.14.0

Next steps

• Tecs Quickstart - Learn ECS concepts and build your first system
• Love2D Integration - Game loop, events, and Love2D phase mapping
• Rendering - Camera, sprites, shapes, lighting
• Input & Controls - Keyboard, mouse, gamepad