feat: comprehensive AI-oriented data model with cell-level map API and knowledge base
- Add cell/tile map APIs: /api/state/cell, /api/state/cells, /api/state/cells/slice, /api/state/gas - Add entity registry APIs: /api/registry/buildings, /api/registry/elements, /api/registry/techs - Add plants, rooms, mop, harvest endpoints - Rich semantic metadata: element state/category, building category/power, duplicant chore/cell - AI-friendly coordinate system with (x,y) + cell index in all responses - Build AI_KNOWLEDGE_BASE.md with building IDs, element IDs, tech trees, game mechanics - Rewrite SKILL.md with data model explanation, coordinate guide, operation patterns - Update Python tools: explore, cell, cells, slice, gas, registry subcommands - Update MOD_DEV_GUIDE.md with AI data design principles
This commit is contained in:
root
268
docs/AI_KNOWLEDGE_BASE.md
Normal file
268
docs/AI_KNOWLEDGE_BASE.md
Normal file
@ -0,0 +1,268 @@
|
||||
# ONI Knowledge Base — AI Reference
|
||||
|
||||
This file aggregates all building IDs, element IDs, tech IDs, and their semantic metadata
|
||||
in one structured document. The AI uses this to understand what each entity means and
|
||||
how to reason about the game.
|
||||
|
||||
## Coordinate System
|
||||
|
||||
ONI uses a 2D grid. The origin (0,0) is at the **bottom-left** of the map.
|
||||
- x increases to the right
|
||||
- y increases upward
|
||||
- Each cell is 1x1 tile
|
||||
- Buildings may occupy multiple cells (width x height); the (x,y) is the **bottom-left anchor**
|
||||
- World size varies by asteroid (default ~256x384 cells)
|
||||
|
||||
When the AI wants to reference a location:
|
||||
- Use absolute (x,y) coordinates
|
||||
- For regions: (x, y, width, height)
|
||||
- For buildings: reference the bottom-left cell of the building
|
||||
- For movement: "at (x,y)" or "from (x1,y1) to (x2,y2)"
|
||||
|
||||
## Building Categories
|
||||
|
||||
| Category | Purpose | Examples |
|
||||
|------------|----------------------------------------|---------------------------------------------------|
|
||||
| Base | Structure, storage, doors, ladders | Tile, Ladder, StorageBin, InsulatedTile, Door |
|
||||
| Oxygen | Oxygen production, gas cleaning | Electrolyzer, OxygenDiffuser, Deodorizer |
|
||||
| Power | Power generation, storage, wiring | CoalGenerator, HydrogenGenerator, Battery |
|
||||
| Food | Food production, cooking, ranching | PlanterBox, ElectricGrill, MicrobeMusher, Ranch |
|
||||
| Plumbing | Liquid handling, hygiene | LiquidPump, Lavatory, WaterSiever, Shower |
|
||||
| Ventilation| Gas handling | GasPump, GasFilter, GasVent |
|
||||
| Refinement | Material processing | MetalRefinery, RockCrusher, Kiln, Compost |
|
||||
| Medicine | Health, disease treatment | Apothecary, MassageTable, SickBay |
|
||||
| Furniture | Decor, morale, stress relief | Cot, MessTable, ArcadeCabinet, FlowerPot |
|
||||
| Stations | Research, suit docks, crafting | ResearchStation, SuperComputer, AtmoSuitDock |
|
||||
| Utilities | Temperature management | ThermoAquatuner, SpaceHeater, TempshiftPlate |
|
||||
| Automation | Logic circuits, sensors | AND Gate, AtmoSensor, AutomationWire |
|
||||
| Shipping | Conveyor systems | ConveyorLoader, ConveyorRail, SolidFilter |
|
||||
|
||||
## Key Building IDs (frequently used by AI)
|
||||
|
||||
```
|
||||
# Oxygen production
|
||||
Electrolyzer -> Produces O2 + H2 from water (needs 1kg/s water)
|
||||
OxygenDiffuser -> Produces O2 from algae (early game)
|
||||
Deodorizer -> Converts PollutedOxygen to Oxygen (needs filtration medium)
|
||||
|
||||
# Power
|
||||
ManualGenerator -> 400W, duplicant powered
|
||||
CoalGenerator -> 600W, consumes Coal
|
||||
HydrogenGenerator -> 800W, consumes H2
|
||||
NaturalGasGenerator-> 800W, consumes NaturalGas
|
||||
PetroleumGenerator -> 2000W, consumes Petroleum
|
||||
SteamTurbine -> Extracts heat from steam, produces power
|
||||
SolarPanel -> 380W max, needs light
|
||||
WoodBurner -> 300W, consumes Lumber
|
||||
|
||||
# Power storage
|
||||
Battery -> 10kJ storage, small
|
||||
JumboBattery -> 40kJ storage
|
||||
SmartBattery -> 20kJ storage, automation output
|
||||
|
||||
# Food
|
||||
PlanterBox -> Grows plants, needs dupe delivery
|
||||
FarmTile -> Grows plants with irrigation
|
||||
HydroponicFarm -> Grows plants with automatic irrigation
|
||||
ElectricGrill -> Cooks food (better quality)
|
||||
MicrobeMusher -> Makes basic mush bars from water + dirt
|
||||
GasRange -> Advanced cooking with gas
|
||||
Refrigerator -> Stores food, slows decay
|
||||
|
||||
# Plumbing
|
||||
LiquidPump -> Pumps liquids (240kg/s)
|
||||
Lavatory -> Produces PollutedWater from dupe use
|
||||
WaterSiever -> Filters PollutedWater -> Water
|
||||
Desalinator -> Removes salt from SaltWater/Brine
|
||||
LiquidVent -> Outputs liquid into world
|
||||
|
||||
# Ventilation
|
||||
GasPump -> Pumps gases (500g/s)
|
||||
GasFilter -> Filters specific gas from mixed pipes
|
||||
GasVent -> Outputs gas into world
|
||||
HighPressureGasVent-> 20kg/tile max pressure
|
||||
|
||||
# Refinement
|
||||
MetalRefinery -> Refines metal ores into refined metals
|
||||
RockCrusher -> Crushes rock into sand/power
|
||||
Kiln -> Burns clay -> ceramic
|
||||
GlassForge -> Makes glass from sand
|
||||
Compost -> Converts polluted dirt into dirt
|
||||
|
||||
# Base
|
||||
Tile -> Standard tile, 2 tiles high
|
||||
Ladder -> Allows vertical movement
|
||||
InsulatedTile -> Reduces heat transfer (best insulation)
|
||||
ManualAirlock -> Manual door
|
||||
PneumaticDoor -> Auto door, lets gas pass
|
||||
MechanizedAirlock -> Auto door, seals gas/liquid
|
||||
StorageBin -> Stores solid resources
|
||||
LiquidReservoir -> Stores 5t of liquid
|
||||
GasReservoir -> Stores 150kg of gas
|
||||
|
||||
# Temperature
|
||||
ThermoAquatuner -> Cools liquid piped through it (needs steam room)
|
||||
ThermoRegulator -> Cools gas piped through it
|
||||
SpaceHeater -> Heats area (inefficient)
|
||||
LiquidTepidizer -> Heats liquid (up to 85C)
|
||||
TempshiftPlate -> Distributes heat evenly
|
||||
|
||||
# Stations
|
||||
ResearchStation -> Basic research (needs dirt)
|
||||
SuperComputer -> Advanced research (needs plastic)
|
||||
AtmoSuitDock -> Stores atmo suit
|
||||
GroomingStation -> Grooms critters for happiness/eggs
|
||||
RanchStation -> Ranching skill station
|
||||
FarmStation -> Improves farm yield (needs fertilizer)
|
||||
PowerControlStation-> Improves generator efficiency
|
||||
|
||||
# Medicine
|
||||
MassageTable -> Reduces stress
|
||||
SickBay -> Cures diseases
|
||||
TriageCot -> Heals physical damage
|
||||
Apothecary -> Produces medicine
|
||||
|
||||
# Automation (common items)
|
||||
AtmoSensor -> Senses gas pressure
|
||||
ThermoSensor -> Senses temperature
|
||||
HydroSensor -> Senses liquid pressure
|
||||
GasElementSensor -> Senses specific gas type
|
||||
AND Gate, NOT Gate, FILTER Gate, BUFFER Gate
|
||||
```
|
||||
|
||||
## Key Element IDs (resources)
|
||||
|
||||
```
|
||||
# Critical survival
|
||||
Oxygen -> Breathable gas (needed by dupes)
|
||||
Water -> Essential for farming, electrolysis, life support
|
||||
Dirt -> Used in research (early) and farming
|
||||
Algae -> Consumed by OxygenDiffuser
|
||||
|
||||
# Food chain
|
||||
Calories -> Aggregate food energy for colony
|
||||
MealLice -> Basic food from mealwood plants
|
||||
BristleBerry -> Mid-tier food from bristle blossom
|
||||
Mushroom -> Food from dusk cap (needs CO2 + slime)
|
||||
RawEgg -> Egg for cooking
|
||||
Meat -> From ranching
|
||||
|
||||
# Power chain
|
||||
Coal -> Burned in CoalGenerator
|
||||
Hydrogen -> Burned in HydrogenGenerator
|
||||
NaturalGas -> Burned in NaturalGasGenerator
|
||||
Petroleum -> Burned in PetroleumGenerator
|
||||
CrudeOil -> Can be refined to Petroleum
|
||||
|
||||
# Construction metals
|
||||
CopperOre -> Early building material
|
||||
IronOre -> Mid building material
|
||||
GoldAmalgam -> High corrosion resistance
|
||||
Wolframite -> Very high melting point (tungsten source)
|
||||
Steel -> Strong, high melting point (refined)
|
||||
RefinedIron -> Mid refined metal
|
||||
Plastic -> Advanced material (from polymer press or dreckos)
|
||||
Ceramic -> Best insulation material
|
||||
|
||||
# Water / liquids
|
||||
SaltWater -> Can be desalinated to Water
|
||||
Brine -> Can be desalinated (more salt per water)
|
||||
PollutedWater -> Can be filtered to Water (also used by reed fiber)
|
||||
CrudeOil -> Pumped from oil biome
|
||||
Petroleum -> Refined from oil (cooking or refinery)
|
||||
Lumber -> From arbor trees, burned in wood burner
|
||||
Ethanol -> From lumber, burned in petroleum generator
|
||||
|
||||
# Gas handling
|
||||
PollutedOxygen -> Can be deodorized to Oxygen
|
||||
CarbonDioxide -> Sinks to bottom, used by mushrooms/soda fountain
|
||||
ChlorineGas -> Disinfects, used by balm lily
|
||||
SourGas -> Can be cooled to methane + sulfur
|
||||
|
||||
# Rare / advanced
|
||||
Niobium -> End-game space material
|
||||
Thermium -> Best heat conductor (space material)
|
||||
Isoresin -> Used for insulation (space material)
|
||||
ViscoGel -> Non-mixing liquid (space material)
|
||||
Radium -> Radioactive, spaced out DLC
|
||||
```
|
||||
|
||||
## Research Tech Tree (simplified path)
|
||||
|
||||
```
|
||||
Tier 0 (start): FarmingTech, PowerRegulation, Plumbing, Ventilation
|
||||
Tier 1: FoodPreparation (-> ElectricGrill, MicrobeMusher)
|
||||
InteriorDecor (-> Cot, FlowerPot, various decor)
|
||||
AdvancedPowerRegulation (-> SmartBattery, PowerTransformer)
|
||||
LiquidPiping (-> LiquidPump, WaterSiever, Desalinator)
|
||||
GasPiping (-> GasPump, GasFilter)
|
||||
FineDining (-> GasRange, Refrigerator)
|
||||
Tier 2: ImprovedOxygen (-> Electrolyzer)
|
||||
RefinedObjects (-> MetalRefinery, RockCrusher)
|
||||
TemperatureModulation (-> ThermoAquatuner, ThermoRegulator)
|
||||
Ranching (-> GroomingStation, Incubator)
|
||||
SmartStorage (-> LiquidReservoir, GasReservoir)
|
||||
Automation (-> first automation buildings)
|
||||
Tier 3: HighTemperatureForging (-> Steel)
|
||||
SpaceProgram (-> telescope, rocket platform)
|
||||
CryoFuelPropulsion (-> hydrogen rocket engine)
|
||||
Tier 4: MaterialsScience (-> SuperCoolant, ViscoGel)
|
||||
```
|
||||
|
||||
## Building Size Reference (width x height)
|
||||
|
||||
```
|
||||
1x1: Wire, GasPipe, LiquidPipe, AutomationWire, Switch, Sensor
|
||||
1x2: ManualGenerator, Battery, PlanterBox, FarmTile, RationBox
|
||||
2x1: GasFilter, LiquidFilter, Incubator, Jukebot
|
||||
2x2: CoalGenerator, HydrogenGenerator, OxygenDiffuser, Electrolyzer,
|
||||
GasPump, LiquidPump, AlgaeTerrarium, Deodorizer, WaterSiever,
|
||||
ElectricGrill, MicrobeMusher, RockCrusher, Kiln, Compost,
|
||||
MassageTable, Apothecary, ResearchStation, TextileLoom
|
||||
2x3: MetalRefinery, PolymerPress, OilRefinery, AtmoSuitDock
|
||||
2x4: Telescope, MolecularForge
|
||||
3x1: LadderBed, DisplayShelf
|
||||
3x2: ManualAirlock, PneumaticDoor, MechanizedAirlock, ConveyorLoader,
|
||||
SmartStorageBin, LiquidReservoir, GasReservoir
|
||||
3x3: Shower, Sauna, HotTub
|
||||
3x4: SteamTurbine
|
||||
4x2: SuperComputer, JumboBattery, StorageBin
|
||||
4x4: SolarPanel
|
||||
```
|
||||
|
||||
## Common Game Mechanics (AI reference)
|
||||
|
||||
### Gas/Liquid Physics
|
||||
- Gases **layer by density**: CO2 (sinks) < O2 < PollutedO2 < NaturalGas < H2 (rises)
|
||||
- Liquids **layer by density**: Petroleum < Water/SaltWater/Brine < CrudeOil < Mercury
|
||||
- Pressure limit for gas vents: GasVent = 2kg/tile, HighPressureGasVent = 20kg/tile
|
||||
- Buildings overheat above their overheat temperature (default 75C, some higher)
|
||||
- Insulated Tile reduces heat transfer by ~100x
|
||||
|
||||
### Duplicant Needs
|
||||
- Oxygen: need ~100g/s per dupe
|
||||
- Food: need ~1000kcal/cycle per dupe
|
||||
- Stress: > 50% starts causing problems, > 80% mental breaks
|
||||
- Temperature: comfortable at 18-35C, hypothermia below 10C, hyperthermia above 40C
|
||||
- Morale: affected by decor, food quality, room bonuses
|
||||
|
||||
### Room Types
|
||||
- Latrine: Outhouse + WashBasin = +1 morale
|
||||
- Washroom: Lavatory + Sink = +2 morale
|
||||
- Barracks: Cot/LadderBed + 1 decor = +1 morale
|
||||
- Bedroom: ComfyBed + 1 decor = +2 morale
|
||||
- Mess Hall: MessTable + 1 decor = +3 morale
|
||||
- Great Hall: MessTable + 2+ decor and recreation = +6 morale
|
||||
- Park: 4+ wild/planted plants = +1 morale
|
||||
- Nature Reserve: 12+ wild plants = +6 morale
|
||||
- Stable: GroomingStation + CritterDropOff = ranching room
|
||||
- Ranch: Incubator + feeder (spaced out)
|
||||
|
||||
### SPOM (Self-Powered Oxygen Module)
|
||||
The classic Rodriguez SPOM:
|
||||
- 1 Electrolyzer (consumes 1kg/s water -> 888g/s O2 + 112g/s H2)
|
||||
- 2 GasPumps for O2 extraction
|
||||
- 1 HydrogenGenerator (burns 100g/s H2, produces 800W)
|
||||
- 1 GasFilter to separate H2 from O2
|
||||
- Net power positive (runs on its own hydrogen)
|
||||
- Standard size: 8x6 tiles
|
||||
Reference in New Issue
Block a user