Docs Reference
Data sources
Where each kind of data comes from and how precise it is. When something looks wrong, check this page first.
| Data | Source | Precision |
|---|---|---|
| Units, resources, orders, abilities, buffs, inventory | World block pushed by the runtime every 50 ms | Publish interval (adjustable down to 16 ms) |
| Damage and kill events | Recorded by the runtime on the game thread, every hit | Immediate |
| Other events (appear, die, order change, level up…) | Diff between two consecutive publishes | Publish interval |
| Production table (train / research / build / upgrade) | Timer fields of the engine’s production abilities + elapsed time accumulated by the runtime | About ±0.2 game seconds |
| Combat stats, counter table | The game’s own data tables (extracted from the game on your machine) | Excludes item, aura and buff modifiers |
| Pathfinding | The engine’s terrain walkability (128 per cell) + trees + building footprints, with A* on the SDK side | One cell; gaps narrower than a cell count as blocked |
| In-game time | JASS GetFloatGameState(GAME_STATE_TIME_OF_DAY) | Publish interval |
| Visibility | Per-unit, per-player visibility mask computed by the runtime | Publish interval |
| Tech counts, feasibility, gold remaining | Fast lane queries straight to the engine | Immediate |
Game data isn’t distributed with the code
Unit tables, abilities, items, heroes, buffs, the damage/counter table and so on come from Blizzard’s game files and are not in the repository. Once you set the game folder in Farsight’s Control Center, they’re extracted from your own game automatically; you can also run it by hand:
python data/tools/extract_game_data.pyThe output goes to data/game/ (not in git): the raw .slk / .txt files, plus the processed units.json, names.json, skills.json, items.json, heroes.json and buffs.json.
Some specific numbers
| Quantity | Value |
|---|---|
| One day | 480 game seconds (240 each for day and night); one hour = 20 game seconds; games start at 8 AM |
| Daytime | 6:00–18:00 |
| Armor coefficient | 0.06 (from the game data tables) |
| World block capacity | 16 players, 1024 units, 256 unit details, 256 ground items, 128 production entries |
| Trees | Up to 4096 destructibles, refreshed every 2 seconds |
| Event ring | 8192 entries; reading too slowly drops events (the SDK can detect this) |
| Map grid | 128 game units per cell, up to 256 × 256 |
Examples calibrated against measurements
- Production times: peasant 14.9, farm 34.9, Iron Forged Swords 59.9 game seconds, matching what the runtime pushes (error under 0.2 seconds);
- Combat stats checked against the in-game panel: Paladin 650 HP, 255 mana, 3.9 armor, attack 24–34; footman with level-1 attack upgrade 13–15;
- Pre-armor damage from engine damage events (14 / 15 / 15) falls within the range computed by
stats(); - Pathfinding: on Echo Isles (116 × 88 cells), the ground distance to the opposing town hall is 10642 (9856 in a straight line); building the grid takes 18 ms, and one A* search takes about 1 ms.