Squad Tactics Kit: Turn-Based Grid Battles with Cover, Hit Chances and Computer Opponents
README.md
tacticsKit
Turn-based squad tactics for any Zero world. Two squads take turns moving across a grid, duck behind half and full cover, and see their odds before they shoot. When you attack, the result always lands inside what the preview said was possible. It works hot-seat on one computer, online between two computers, or against the computer, and plays with keyboard and mouse, a gamepad or a touch screen.
Version 1.0.7 (require("tacticsKit.api").VERSION).
Five minutes from an empty world to a playable skirmish
-
Install
tacticsKit.packagefrom ZeroMind (search "tacticsKit" or "turn-based tactics kit"). The install brings everything it runs on: gridKit (grid rules, sight, cover, highlight looks), forecastKit / Calculated Odds (hit chance, graze and damage previews, result styles), turnAiKit / Next Move (the computer opponent), SecondWind with Lifeline and MatchFlow (health), markersKit (damage numbers), juiceKit (hit feedback), menusKit (victory and defeat screens), toasts and Field Command's unit models. It is a large install (about 9,000 files with its dependencies) and takes a few minutes. -
Optional: install desertProps (search "desertProps") for the ruin looks. With it, every cover piece is drawn as the desert ruin its map names (broken walls, columns, crates, a fallen statue head). Without it the kit draws each piece as stone blocks, 1.6 m tall for full cover and 0.8 m for half, so a fresh world plays straight away. desertProps is large (about 12,000 files), which is why it is not installed for you.
-
Make a scene for the battle. In the console run
asset.create("scene", "skirmish", { folder = "scenes" })(or add a scene from the editor's asset panel), then replace the newscenes/skirmish.scene/build.luauwith:local TK = require("tacticsKit.api") function content() -- ground and light local ground = entity.spawn("ground") ground.component.add("Model", { model = "cube", material = asset.resolve("@builtin::materials.lit_checkerboard", "material") }) ground.component.add("BoxCollider", {}) ground.localPosition = { 0, -0.1, 0 } ground.localScale = { 60, 0.2, 60 } entity.spawn("sun").component.add("Light", { kind = "directional", intensity = 3, directionX = -0.4, directionY = -0.8, directionZ = -0.3 }) entity.spawn("sky").component.add("ProceduralSky", { timeOfDay = 15 }) -- the player: a tactics camera that orbits the board local setups = entity.spawn("PlayerSetups") local prototype = entity.spawn("Player", { parent = setups }) prototype:setParticipation("PrototypeOnly") local body = entity.spawn("body", { parent = prototype }) body.component.add("Asset", { source = asset.resolve("@builtin::avatars.humanoid", "avatar") }) local rig = entity.spawn("CameraRig", { parent = prototype }) rig:setNetworkScope("OwnerOnly") TK.useCamera(rig) prototype.component.add("PlayerPrototype", { body = body, camera = rig }) entity.spawn("Spawn", { position = { -20, 0, 0 } }).component.add("PlayerSpawn", { prototype = prototype }) -- the battle: a synced match, centred here, Red played by the computer TK.Skirmish { map = "sunkenCourt", position = { 0, 0, 0 }, seat2 = "ai" } endOpen the scene (and make it the startup scene in the world settings so players land in it).
Why a new scene rather than the starter one: a brand-new world's starter scene can carry recorded editor edits (on its lamps, its sun and its player prototype) that make the engine refuse a rebuild after you change its
build.luau("composition has structural conflicts"). A scene of your own has none. To put the battle in an existing scene instead, add theTK.Skirmish { ... }line andTK.useCamera(rig)(whererigis your player prototype's camera rig) to itscontent(). -
Press Play. The setup panel opens: pick who plays each side (a player here, a player online, or the computer with a personality and difficulty), the squads, the fantasy or sci-fi look, the map, how to win and the turn order. Press Start battle (a gamepad's D-pad and A, or a tap, reach it too).
That is a full 4 v 4 game: blue goes first, "YOUR TURN" shows, click a soldier, click a cell to move, hover an enemy to see the hit chance and damage, click it and confirm to fire. Take out the enemy commander or half their squad (rout), or stand alone on the glowing altar stones for three of your turns (hold).
Controls
| keyboard + mouse | gamepad | touch | |
|---|---|---|---|
| select / move / aim | click | stick or d-pad moves the cell cursor, A | tap a unit or cell |
| confirm (fire, move) | click the same target again, Enter | A | tap again, or Confirm |
| cancel | right click, Backspace | B | Cancel |
| next unit | Tab | X | Next unit |
| abilities | 1-4, R / F to cycle | RB / LB | the ability buttons |
| end turn | T | Y | End turn |
| pause menu | Esc | Start | the round Menu button (bottom-right; the HUD keeps that corner clear on phones) |
| camera | WASD pan, Q/E turn, wheel zoom, middle-drag, right-drag | right stick (turn, zoom); follows the cursor | drag to pan, pinch to zoom, twist to turn |
What you get
| part | what it is |
|---|---|
tacticsKit.api | TK.Skirmish{}, TK.useCamera(rig), TK.match(), and TK.Rules, TK.Units, TK.Abilities, TK.Maps, TK.AI |
TacticsMatch component | one networked match: setup panel, seats, turns, input, HUD, computer turns |
TacticsCamera component | the orbiting tactics camera |
units | 8 unit types x 2 looks, 4 squads; Units.define adds more |
abilities | 17 actions and 9 status effects as data; Abilities.define adds more |
maps | Sunken Court and Broken Causeway; Maps.define adds more |
rules | the whole game as pure, deterministic functions (tests and the AI use it with no scene) |
view, hud | what each player sees (highlights, models, cover, animations) and the panels |
ai | the adapter that lets turnAiKit play a match |
art | the heavy and shield-bearer miniatures in both looks (the other six types use Field Command's models) |
tactics input map | the controls on every device |
tacticsKit test suite | 12 tests |
| guides | "How to make a turn-based tactics game" and "Example: add a new unit type and a second map" |
reuse-review.md | every part the kit and the Hold the Line skirmish installed, rated 1 to 5 with the reason |
The roster
| type | fantasy | sci-fi | move | range | hp | specials |
|---|---|---|---|---|---|---|
| soldier | Footman | Trooper | 4 | 6 | 10 | Rapid Fire, Hunker Down |
| scout | Outrider | Hover Scout | 6 | 5 | 7 | Mark Target, Hit and Run |
| heavy | Juggernaut | Gunner | 3 | 5 | 14 (armour 1) | Suppress, Shred |
| sniper | Longbow | Ranger | 3 | 10 (min 2) | 7 | Aimed Shot, Camouflage |
| medic | Priestess | Field Medic | 4 | 4 | 8 | Heal, Screen |
| grenadier | Siege Mage | Rail Walker | 3 | 6 | 9 | Blast (area, wrecks half cover), Concussion |
| shield | Shield Bearer | Bulwark | 4 | 1 (melee) | 12 (armour 1) | Shield Wall, Shield Bash |
| commander | King | Commander | 4 | 6 | 12 (armour 1) | Command (extra action), Inspire |
Each side picks its look: look1 = "fantasy" | "scifi", look2 = .... Squads: assault, recon, siege, vanguard (squad1, squad2), or a list of four type ids.
Rules in one breath
Each unit has 2 actions a turn. Moving costs one; attacking or most specials end the unit's turn. Full cover (walls, statues, standing columns) blocks sight and gives -40 to hit; half cover (crates, barrels, stumps) gives -20 and does not block sight. Cover only counts from the side it faces the attacker; standing next to cover that faces away is flanked (no cover, +10 crit). Range beyond a unit's optimal distance costs 5% a cell. A shot that just misses can graze: the band of rolls just above the hit chance (up to 15 points) clips the target for half damage (at least 1, never a crit, no on-hit effect). The preview shows the graze chance and graze damage beside the hit chance. Every hit chance, damage range, crit chance and kill chance comes from forecastKit, and the roll is forecastKit's deterministic resolve with the match seed, so every machine gets the same result and it always lies inside the preview. Matches end on rout (commander down, or half the squad), hold (alone on the objective at the end of holdTurns of your turns) or, after maxRounds (12), by who has more standing.
Turn order: turnOrder = "sides" (all of one side, then the other) or "initiative" (every unit acts alone, fastest first, re-ordered each round).
Seats and multiplayer
seat1 / seat2 = "human" or "ai". A human seat nobody has claimed is played by whoever is at the controls, so two people on one computer just pass the mouse (hot-seat). On the setup panel Play this side here claims a seat for your machine: from then on only you give that side orders (online). Any seat can be the computer, with ai1/ai2 = balanced, aggressive, defensive, objective, skirmisher, flanker, bodyguard and diff1/diff2 = easy, normal, hard.
The match state is one synced string written by the room's host (the owner of the match entity). Other players' actions are sent to the host with multiplayer.send, checked against the rules and the seats, applied, and every machine animates the same events from the new state. A player who joins late sees the board as it stands, can take a free seat with Play this side here, and both players carry on. Only the owner of the match entity ever writes the match state: a machine that has not yet received the synced match never acts as the host. Every order carries the board revision it was made against, so a request that crossed a newer move is refused instead of applied twice, and an order the host has not answered is sent again (a toast says so if the host stops answering).
Looks you can switch with one change
| what | field / call | choices |
|---|---|---|
| attack preview layout | previewStyle (per player) | big, duel, tooltip, minimal |
| attack preview theme | previewTheme (per player) | clean, scifi, fantasy, pixel, cartoon |
| shot result style | resultStyle (per player) | stamp (a word stamped over the target), burst (a big number on a starburst), ticker (a compact line with the roll against the chance), banner (a full-width result band) |
| cell highlights | highlight (per player) | any gridKit look: hologram, outline, fill, glow, pixel, dotted, pulse, decal |
| unit looks | look1, look2 | fantasy, scifi |
| cover looks | install desertProps | desert ruins, or stone blocks without it |
| results screens | menuTheme | any menusKit look |
API
local TK = require("tacticsKit.api")
| call | does |
|---|---|
TK.Skirmish(opts) | spawns a synced TacticsMatch (every field above) plus the health bar and damage number HUDs; position, name, hud = false |
TK.useCamera(rig) | gives a player camera rig the TacticsCamera behaviour |
TK.match(name?) | the match component: :match() (state), :act(action), :start(), :rematch(), :backToSetup(), :configure(key, value), :claimSeat(side) |
TK.Rules.new(cfg) | a match as data: preview, apply, reach, targets, canSee, cover, encode/decode |
TK.AI.safeNext(m, side, opts) | the computer's next action |
TK.Units.define, TK.Abilities.define, TK.Maps.define | add unit types, actions and maps |
Actions: { op = "move", unit, q, r }, { op = "attack", unit, target, ability? }, { op = "ability", unit, ability, target? | q, r }, { op = "wait", unit }, { op = "end" }.
Known limits
- Boards are square grids lying flat; the board does not rotate with its entity.
- The ruin cover props come from desertProps, which you install yourself; without it cover is drawn as stone blocks. A map for another setting names other prop kinds (or none, and gets the blocks).
- The computer thinks on the host; on a slow machine a hard computer turn takes a moment per unit.
- Two engines signed in to the same account count as one player (an engine limit), so an online test needs two accounts.
Versions
- 1.0.7: online play with a late joiner no longer freezes: a joining machine never acts as the host before it has the synced match (it used to be able to write its own blank match over the real one), orders carry the board revision and are re-sent if unanswered, and a replaced match component stops answering requests. Touch controls: the HUD reads where the engine's touch overlay puts its buttons (bottom-right on phones, top-right on wide screens) and keeps the turn bar, squad list, unit card and turn buttons clear of them at every screen size; the hit-chance card is placed clear of the HUD (needs Calculated Odds 1.0.4,
opts.avoid), and on a short landscape screen it takes the unit card's place while you aim. Lighter: highlights and the HUD rebuild only when the board, the selection, the pointer cell or the screen changes, and settled units no longer rewrite their rotation every frame (the kit's own script time per frame went from about 1.1 ms to about 0.15 ms on a desktop). Names: every description now says Calculated Odds (forecastKit) and Next Move (turnAiKit). - 1.0.6: graze shots and result styles, from forecastKit (Calculated Odds) 1.0.2: grazes clip for reduced damage, show in every preview and in the log ("grazed for 2"), and a new per-player
resultStylefield (stamp, burst, ticker, banner; also a Result button on the setup panel) picks how hits, crits, grazes, misses and heals are shown. Dependencies renamed as asked: the hit-chance package oddsKit ("Odds On") is now forecastKit ("Calculated Odds"), and the computer-opponent package turnBrain ("Turn Brain") is now turnAiKit ("Next Move") 1.0.1, whose 7 personalities now measurably differ at every difficulty. Fixes: in hot-seat the next side's move range shows the moment its turn starts; a rematch starts clean (no caption, toast or banner left over); pointing or tapping at a unit picks that unit at every zoom (units are picked by their bodies, and taps no longer carry a stale offset); on phones the HUD keeps the touch controls' Menu corner clear, and a gamepad or a portrait touch screen plays a full turn. - 1.0.5: polish. The desertProps check runs again for every board (installing or removing desertProps no longer needs a restart, and a prop that fails to draw switches the rest of the board to stone). Turns read more clearly: in hot-seat the camera swings round behind the side whose turn it is, units with no actions left get a dimmed ring, and the unit that acts first pops when a turn starts. Hits and misses feel better: a hit makes the target flinch away from the shot with a screen kick (bigger on heavy hits and crits), a miss makes the target sidestep with a dust puff, and a kill lands with a short freeze-frame. Phones: the compact layout now also kicks in on short (landscape) screens, the turn bar shortens to fit a portrait phone, and in landscape the unit card stays a narrow corner card so the board stays clear.
- 1.0.4: cover fixes found by installing the kit into a world that has desertProps: the ruins are drawn again when desertProps is installed (the check now asks for the package, which
asset.existsanswers), and the stone blocks drawn without it use two materials shipped in the kit (tacticsKit.materials.stoneBlock,stoneCap) instead of runtime materials that could be released when play starts. - 1.0.3: packaging: the quick start now makes a scene of its own (a brand-new starter scene can refuse rebuilds over leftover editor edits), checked on a fresh install; the example guide's Oasis Gate map passes
Maps.check(a fallen column sat on the objective) and its self-play loop always ends;reuse-review.mdrates every part the kit and the skirmish installed. - 1.0.2: controller and touch fixes: the pad and arrow-key cursor and the camera pan (WASD, right stick, drag) moved the wrong way sideways; a tap on a touch screen was handled twice (the engine's mouse copy of the touch moved a unit at once instead of the tap-then-confirm a touch screen gets). New
match:cursorCell(). - 1.0.1: online play fixes: the host is held to the same seat rule as everyone else (it can no longer give orders for the other player's side), and each machine shows VICTORY or DEFEAT by the side it holds (both showed DEFEAT before).
- 1.0.0: first release. Eight unit types in two looks, 17 actions, two maps, rout / hold / time wins, side and initiative turns, hot-seat / online / computer seats, forecastKit previews, turnAiKit opponent, keyboard / gamepad / touch, stone-block cover when desertProps is not installed, 12 tests.