🌍 Map & Environment API¶

This section covers interacting with the physical game world, weather, buildings, and zones.

Map Controller¶

Сосредоточен на Локальной карте, выбранной по map_id. Он управляет физическим ландшафтом и условиями в непосредственной близости от поселения.

Scope

Этот контроллер имеет дело с окружающей средой, а не с сущностями внутри неё. Для пешек или предметов см. их соответствующие контроллеры.

Возможности:

Изменение локальной погоды.
Запрос размера и границ карты.
Изменение ландшафта (установка полов, очистка от мусора).

GET


/api/v1/map/things

¶

Возвращает полный список всех объектов (things), присутствующих на текущей карте.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/map/things?map_id=0

Response:

{
    "success": true,
    "data": [
        {
            "thing_id": 2328,
            "def_name": "ChunkGranite",
            "label": "granite chunk",
            "categories": [
                "StoneChunks"
            ],
            "position": {
                "x": 41,
                "y": 0,
                "z": 1
            },
            "stack_count": 1,
            "market_value": 0.0,
            "is_forbidden": false,
            "quality": -1,
            "hit_points": 300,
            "max_hit_points": 300
        },
        {
            "thing_id": 4895,
            "def_name": "MealSurvivalPack",
            "label": "packaged survival meal",
            "categories": [
                "FoodMeals"
            ],
            "position": {
                "x": 13,
                "y": 0,
                "z": 62
            },
            "stack_count": 1,
            "market_value": 24.0,
            "is_forbidden": true,
            "quality": -1,
            "hit_points": 50,
            "max_hit_points": 50
        },
        <...>
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/maps

¶

Получает список всех загруженных в данный момент карт в игровой сессии.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/maps

Response:

{
    "success": true,
    "data": [
        {
        "id": 0,
        "index": 0,
        "seed": 16622162,
        "faction_id": "14",
        "is_player_home": true,
        "is_pocket_map": false,
        "is_temp_incident_map": false,
        "size": "(150, 1, 150)"
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:38:45.9289233Z"
}

GET


/api/v1/map/pawns

¶

Получает список всех поселенцев/пешек, присутствующих на указанной карте. Возвращает ключевую информацию о состоянии, такую как здоровье, настроение и положение для каждого.

curl --request GET \
--url 'http://localhost:8765/api/v1/map/pawns?mapId=0'

Response:

{
    "success": true,
    "data": [
        {
            "id": 148,
            "name": "Val",
            "gender": "Female",
            "age": 25,
            "health": 1.0,
            "mood": 0.85,
            "hunger": 0.2,
            "position": {
                "x": 102,
                "y": 0,
                "z": 115
            }
        },
        {
            "id": 149,
            "name": "Stumpy",
            "gender": "Male",
            "age": 42,
            "health": 0.65,
            "mood": 0.4,
            "hunger": 0.8,
            "position": {
                "x": 105,
                "y": 0,
                "z": 112
            }
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-31T14:30:00.0000000Z"
}

GET


/api/v1/map/terrain

¶

Возвращает полные данные о сетке ландшафта и пола для указанной карты.

Примечание к формату данных: Для оптимизации пропускной способности эта конечная точка использует кодирование длин серий (Run-Length Encoding, RLE) и палитру (Palette Mapping).

palette: Список уникальных определений ландшафта (например, "Soil", "WaterDeep").
grid: Сжатый список целых чисел, представляющих ячейки карты. Формат — пары [count, palette_index].

Пример декодирования: Сетка [10, 0, 5, 2] означает "10 ячеек palette[0], за которыми следуют 5 ячеек palette[2]".

Example:

curl --request GET \
--url http://localhost:8765/api/v1/map/terrain?map_id=0

Response:

{
    "success": true,
    "data": {
        "width": 250,
        "height": 250,
        "palette": [
            "Soil",
            "Gravel",
            "SoilRich",
            "WaterDeep"
        ],
        "grid": [
            22,
            0,
            5,
            1,
            500,
            0,
            10,
            3
        ],
        "floor_palette": [
            "WoodPlankFloor",
            "TileSandstone"
        ],
        "floor_grid": [
            62400,
            0,
            50,
            1,
            50,
            2
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T13:12:28.8217513Z"
}

GET


/api/v1/map/things-at

¶

Возвращает список объектов, расположенных в определенной ячейке по её координатам.

Примечание: В отличие от стандартных GET-запросов, эта конечная точка требует тело JSON, содержащее координаты.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/map/things-at \
--header 'Content-Type: application/json' \
--data '{
    "map_id": 0,
    "position": { "x": 15, "y": 0, "z": 25 }
}'

Request Body:

{
    "map_id": 0,
    "position": {
        "x": 15,
        "y": 0,
        "z": 25
    }
}

Response:

{
    "success": true,
    "data": [
        {
            "thing_id": 4895,
            "def_name": "MealSurvivalPack",
            "label": "packaged survival meal",
            "position": { "x": 15, "y": 0, "z": 25 },
            "stack_count": 10
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T13:40:00.000Z"
}

GET


/api/v1/map/things/radius

¶

Возвращает список всех объектов, найденных в указанном радиусе вокруг центральной точки. Полезно для поиска ближайших ресурсов или врагов.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/map/things/radius?map_id=0&x=120&z=120&radius=10"

Response:

{
    "success": true,
    "data": [
        {
            "thing_id": 2328,
            "def_name": "ChunkGranite",
            "label": "granite chunk",
            "position": { "x": 121, "y": 0, "z": 119 },
            "stack_count": 1
        },
        {
            "thing_id": 5012,
            "def_name": "Steel",
            "label": "steel",
            "position": { "x": 118, "y": 0, "z": 122 },
            "stack_count": 35
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T13:42:00.000Z"
}

GET


/api/v1/map/ore

¶

Возвращает сжатый словарь всех залежей руды на карте.

Структура: * Ключи — это имена определений руды (например, "MineableSteel"). * cells содержит индексы ячеек карты, где находится руда. * hp содержит текущее здоровье блока руды в соответствующем индексе (параллельные массивы).

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/map/ore?map_id=0"

Response:

{
    "success": true,
    "data": {
        "map_width": 250,
        "ores": {
            "MineableSteel": {
                "max_hp": 1500,
                "cells": [
                    12500,
                    12501,
                    12502
                ],
                "hp": [
                    1500,
                    1500,
                    850
                ]
            },
            "MineableGold": {
                "max_hp": 500,
                "cells": [
                    3005
                ],
                "hp": [
                    500
                ]
            }
        }
    },
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/map/fog-grid

¶

Извлекает сетку видимости (туман войны) для текущей карты.

fog_data — это плоское строковое представление сетки, где Index = (z * Width) + x.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/map/fog-grid?map_id=0"

Response:

{
    "success": true,
    "data": {
        "map_id": 0,
        "width": 250,
        "height": 250,
        "fog_data": "AQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHyAhIiMkJSYnKCkqKywtLi8wMTIzNDU2Nzg5Ojs8PT4/QEFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaW1xdXl9gYWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXp7fH1+fw=="
    },
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/map/plants

¶

Возвращает список всех растений, расположенных на указанной карте. Сюда входят дикие растения (деревья, кусты, трава) и посеянные культуры.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/map/plants?map_id=0"

Response:

{
    "success": true,
    "data": [
        {
            "thing_id": 1024,
            "def_name": "Plant_TreeOak",
            "label": "oak tree",
            "position": { "x": 45, "y": 0, "z": 88 },
            "growth": 0.85
        },
        {
            "thing_id": 1025,
            "def_name": "Plant_Potato",
            "label": "potato plant",
            "position": { "x": 50, "y": 0, "z": 50 },
            "growth": 0.45
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T14:12:00.000Z"
}

GET


/api/v1/map/weather

¶

Получает текущие погодные условия и температуру для текущей активной карты (карты, которую просматривает игрок).

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/map/weather?map_id=0'

Response:

{
    "success": true,
    "data": {
        "weather": "Rain",
        "temperature": 19.7876511
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:39:54.5380426Z"
}

GET


/api/v1/map/animals

¶

Получает список всех животных, присутствующих в данный момент на активной карте. Сюда входят как дикие животные, так и прирученные/собственные (питомцы, скот, животные караванов).

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/map/animals?map_id=0'

Response:

{
    "success": true,
    "data": [
        {
        "id": 3633,
        "name": "Colin",
        "def": "Yak",
        "faction": "PlayerColony",
        "position": {
            "x": 67,
            "y": 119,
            "z": 0
        },
        "pregnant": false
        },
        {
        "id": 8547,
        "name": "Hare",
        "def": "Hare",
        "position": {
            "x": 50,
            "y": 40,
            "z": 0
        },
        "pregnant": false
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:41:34.3358819Z"
}

GET


/api/v1/map/zones

¶

Получает список всех определенных зон и областей на активной карте. Зоны назначаются игроком, а области имеют конкретное назначение, такие как постройка крыши, очистка от загрязнения и т. д.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/map/zones?map_id=0'

Response:

{
    "success": true,
    "data": {
        "zones": [],
        "areas": [
            {
                "id": 0,
                "cells_count": 0,
                "label": "Home",
                "base_label": "Home",
                "type": "Area_Home"
            },
            {
                "id": 1,
                "cells_count": 0,
                "label": "Build roof",
                "base_label": "Build roof",
                "type": "Area_BuildRoof"
            },
            {
                "id": 2,
                "cells_count": 0,
                "label": "No roof",
                "base_label": "No roof",
                "type": "Area_NoRoof"
            },
            {
                "id": 3,
                "cells_count": 0,
                "label": "Snow clear",
                "base_label": "Snow clear",
                "type": "Area_SnowClear"
            },
            {
                "id": 4,
                "cells_count": 0,
                "label": "Pollution clear",
                "base_label": "Pollution clear",
                "type": "Area_PollutionClear"
            },
            {
                "id": 5,
                "cells_count": 0,
                "label": "Area 1",
                "base_label": "Area 1",
                "type": "Area_Allowed"
            }
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:42:50.3515476Z"
}

GET


/api/v1/map/building/info

¶

Получает подробную информацию о конкретном здании на активной карте по его уникальному идентификатору.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/building/info?id=51058'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:53:16.733319Z"
}

POST


/api/v1/map/weather/change

¶

Вручную изменяет текущие погодные условия на активной карте.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/weather/change?map_id=0&name=Clear'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:53:16.733319Z"
}

GET


/api/v1/map/power/info

¶

Предоставляет подробную информацию об энергосети на текущей карте, включая генераторы, аккумуляторы, потребителей, баланс сети и статус потока энергии.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/map/power/info?map_id=0

Response:

{
    "success": true,
    "data": {
        "produce_power_buildings": [],
        "consume_power_buildings": [],
        "store_power_buildings": [],
        "current_power": 0,
        "total_possible_power": 0,
        "currently_stored_power": 0,
        "total_power_storage": 0,
        "total_consumption": 0,
        "consumption_power_on": 0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:48:05.7377482Z"
}

GET


/api/v1/map/creatures/summary

¶

Возвращает сводный подсчет и классификацию всех существ (пешек) на текущей карте.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/creatures/summary?map_id=0

Response:

{
    "success": true,
    "data": {
        "colonists_count": 3,
        "prisoners_count": 0,
        "enemies_count": 0,
        "animals_count": 5,
        "insectoids_count": 0,
        "mechanoids_count": 0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:49:21.2287056Z"
}

GET


/api/v1/map/farm/summary

¶

Получает сводку по всей фермерской деятельности на текущей карте, включая посаженные культуры, стадии роста, плодородие почвы и ожидаемую урожайность.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/farm/summary?map_id=0

Response:

{
    "success": true,
    "data": {
        "total_growing_zones": 0,
        "total_plants": 0,
        "total_expected_yield": 0,
        "total_infected_plants": 0,
        "growth_progress_average": 0.0,
        "crop_types": []
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:52:41.9403791Z"
}

POST


/api/v1/map/zone/growing

¶

Создать новую зону выращивания для определенного типа растений в списке целевых ячеек. Ячейки, находящиеся вне границ или уже занятые другими зонами, будут пропущены.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/zone/growing' \
--header 'content-type: application/json' \
--data '{
  "map_id": 0,
  "plant_def": "Plant_Rice",
  "point_a": {"x":120,"y":0,"z":130},
  "point_b": {"x":125,"y":0,"z":135}
}'

Request:

{
  "map_id": 0,
  "plant_def": "Plant_Rice",
  "point_a": {"x":120,"y":0,"z":130},
  "point_b": {"x":125,"y":0,"z":135}
}

Response:

{
  "success": true,
  "data": {
    "zone": {
      "id": 5,
      "cells_count": 36,
      "label": "Growing zone 1",
      "base_label": "Growing zone"
    },
    "plant_def_name": "Plant_Rice",
    "plant_count": 6,
    "def_expected_yield": 174,
    "expected_yield": 0,
    "infected_count": 0,
    "growth_progress": 0.202831179,
    "is_sowing": true,
    "soil_type": "Mud",
    "fertility": 0.6,
    "has_dying": false,
    "has_dying_from_pollution": false,
    "has_dying_from_no_pollution": false
  },
  "errors": [],
  "warnings": [],
  "timestamp": "2026-03-28T13:51:53.9267279Z"
}

GET


/api/v1/map/rooms

¶

Возвращает список всех комнат на карте с их характеристиками, такими как роль, температура и количество ячеек.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/rooms?map_id=0

Response:

{
    "success": true,
    "data": {
        "rooms": [
        {
            "id": 5,
            "role_label": "none",
            "temperature": 4.217273,
            "cells_count": 0,
            "touches_map_edge": false,
            "is_prison_cell": false,
            "is_doorway": false,
            "open_roof_count": 0,
            "contained_beds_ids": []
        },
        {
            "id": 61,
            "role_label": "bedroom",
            "temperature": 4.217273,
            "cells_count": 6,
            "touches_map_edge": false,
            "is_prison_cell": false,
            "is_doorway": false,
            "open_roof_count": 6,
            "contained_beds_ids": [
            8408
            ]
        }
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:57:48.1578638Z"
}

GET


/api/v1/map/buildings

¶

Получает исчерпывающий список всех зданий и сооружений, присутствующих на активной карте.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/map/buildings?map_id=0'

Response:

{
    "success": true,
    "data": [
        {
            "id": 8880,
            "def": "Turret_MiniTurret",
            "label": "steel mini-turret",
            "position": {
                "x": 60,
                "y": 0,
                "z": 86
            },
            "type": "Building_TurretGun"
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:46:33.2115192Z"
}

POST


/api/v1/map/destroy/corpses

¶

Уничтожает все трупы на карте.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/destroy/corpses

POST


/api/v1/map/destroy/forbidden

¶

Уничтожает все запрещенные предметы на карте.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/destroy/forbidden

POST


/api/v1/map/destroy/rect

¶

Уничтожает все объекты в указанном прямоугольнике на карте.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/destroy/rect \
--header 'content-type: application/json' \
--data '{
    "map_id": 0,
    "point_a": {"x": 7, "y": 0, "z": 7},
    "point_b": {"x": 32, "y": 0, "z": 32}
}'

Request:

{
    "map_id": 0,
    "point_a": {"x": 7, "y": 0, "z": 7},
    "point_b": {"x": 32, "y": 0, "z": 32}
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-31T11:04:27.9729153Z"
}

POST


/api/v1/map/repair/positions

¶

Ремонтирует предметы, размещенные по предоставленному списку позиций.

POST


/api/v1/map/repair/rect

¶

Ремонтирует все подлежащие ремонту предметы в указанном прямоугольнике на карте.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/map/repair/rect \
--header 'content-type: application/json' \
--data '{
    "map_id": 0,
    "point_a": {"x": 7, "y": 0, "z": 7},
    "point_b": {"x": 32, "y": 0, "z": 32}
}'

Request:

{
    "map_id": 0,
    "point_a": {"x": 7, "y": 0, "z": 7},
    "point_b": {"x": 32, "y": 0, "z": 32}
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-31T11:04:27.9729153Z"
}

POST


/api/v1/map/droppod

¶

Создает десантную капсулу (drop pod) в указанной позиции с заданным содержимым.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/droppod' \
--header 'content-type: application/json' \
--data '{
    "map_id": 0,
    "position": {"x": 15, "y": 0, "z": 15},
    "items": [{"def_name": "ComponentIndustrial", "quality": 3, "count": 1}],
    "open_delay": true
}'

Request:

{
    "map_id": 0,
    "position": {"x": 15, "y": 0, "z": 15},
    "items": [{"def_name": "ComponentIndustrial", "quality": 3, "count": 1}],
    "open_delay": true
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-31T11:04:27.9729153Z"
}

POST


/api/v1/map/zone/stockpile

¶

Создать новую зону склада на карте с определенными границами координат и фильтрами предметов.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/zone/stockpile' \
--header 'content-type: application/json' \
--data '{
    "map_id": 0,
    "point_a": {"x": 10, "y": 0, "z": 10},
    "point_b": {"x": 15, "y": 0, "z": 15},
    "name": "High Quality Steel",
    "priority": 4,
    "allowed_item_defs": ["Steel"],
    "allowed_item_categories": [],
    "min_hit_points_percent": 0.5,
    "max_hit_points_percent": 1.0,
    "min_quality": "Normal",
    "max_quality": "Legendary"
}'

Request:

{
    "map_id": 0,
    "point_a": {"x": 10, "y": 0, "z": 10},
    "point_b": {"x": 15, "y": 0, "z": 15},
    "name": "High Quality Steel",
    "priority": 4,
    "allowed_item_defs": ["Steel"],
    "allowed_item_categories": [],
    "min_hit_points_percent": 0.5,
    "max_hit_points_percent": 1.0,
    "min_quality": "Normal",
    "max_quality": "Legendary"
}

Response:

{
  "success": true,
  "data": {
    "zone_id": 6,
    "name": "Stockpile 3",
    "cells_count": 36,
    "priority": 0,
    "success": true,
    "message": "Stockpile 'Stockpile 3' created successfully with 36 cells."
  },
  "errors": [],
  "warnings": [],
  "timestamp": "2026-03-28T13:52:52.7387655Z"
}

POST


/api/v1/map/zone/stockpile/update

¶

Обновить параметры существующей зоны склада, включая разрешенные предметы, категории и фильтры качества/ОЗ.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/zone/stockpile/update' \
--header 'content-type: application/json' \
--data '{
    "zone_id": 142,
    "name": "Updated Steel & Wood",
    "priority": 5,
    "add_item_defs": ["WoodLog"],
    "remove_item_defs": [],
    "add_item_categories": [],
    "remove_item_categories": [],
    "min_hit_points_percent": 0.1,
    "max_hit_points_percent": 1.0,
    "min_quality": "Awful",
    "max_quality": "Legendary"
}'

Request:

{
    "zone_id": 142,
    "name": "Updated Steel & Wood",
    "priority": 5,
    "add_item_defs": ["WoodLog"],
    "remove_item_defs": [],
    "add_item_categories": [],
    "remove_item_categories": [],
    "min_hit_points_percent": 0.1,
    "max_hit_points_percent": 1.0,
    "min_quality": "Awful",
    "max_quality": "Legendary"
}

Response:

{
    "success": true,
    "data": {
        "zone_id": 142,
        "name": "Updated Steel & Wood",
        "cells_count": 36,
        "priority": 5,
        "success": true,
        "message": null
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2026-03-28T14:35:00.0000000Z"
}

DELETE


/api/v1/map/zone/stockpile/delete

¶

Удалить зону склада по её ID.

Example:

curl --request DELETE \
--url 'http://localhost:8765/api/v1/map/zone/stockpile/delete?zone_id=142'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2026-03-28T14:40:00.0000000Z"
}

POST


/api/v1/map/building/power

¶

Переключить состояние питания (вкл/выкл) для переключаемого здания (например, солнечные лампы, турели, производственные станки) через его компонент CompFlickable.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/map/building/power?buildingId=123&powerOn=true'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2026-03-28T16:00:00.0000000Z"
}

GET


/api/v1/datetime

¶

Возвращает текущую игровую дату и время в соответствии с мировым календарем RimWorld.

Пример:

curl --request GET \
--url http://localhost:8765/api/v1/datetime

Ответ:

{
    "success": true,
    "data": {
        "datetime": "12th of Aprimay, 5500, 17h"
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:05:35.3244951Z"
}

GET


/api/v1/datetime/tile

¶

Возвращает игровую дату и время с учётом сезонного смещения конкретного тайла мира.

Пример:

curl --request GET \
--url 'http://localhost:8765/api/v1/datetime/tile?tile=42'

Ответ:

{
    "success": true,
    "data": {
        "datetime": "12th of Aprimay, 5500, 17h"
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:05:35.3244951Z"
}

Глобальная карта¶

Работает на планетарном масштабе. Этот контроллер взаимодействует с объектами, которые существуют на карте мира, а не на локальной карте колонии.

Караваны: Отслеживание перемещения, ожидаемого времени прибытия (ETA) и инвентаря путешествующих групп.
Поселения: Поиск баз других фракций и мест выполнения квестов.
Гексы (Tiles): Запрос данных о биоме, температуре и ландшафте для конкретных секторов мира.

GET


/api/v1/world/caravans

¶

Возвращает список всех активных караванов, находящихся в данный момент на карте мира. Сюда входят караваны игрока и видимые караваны других фракций. Возвращает подробности о местоположении, пункте назначения и содержимом (существа/предметы).

Example:

curl --request GET \
--url http://localhost:8765/api/v1/world/caravans

Response:

{
    "success": true,
    "data": [
        {
        "id": 11,
        "name": "Rosa's caravan",
        "is_player_controlled": true,
        "position": {
            "x": 1,
            "y": 65,
            "z": -75
        },
        "tile": 232,
        "pawns": [
            {
            "id": 74,
            "name": "Rosa"
            }
        ],
        "items": [
            {
            "thing_id": 74,
            "def_name": "Human",
            "label": "Rosa<color=#999999FF>, Explorer</color>",
            "categories": [],
            "position": {
                "x": 143,
                "y": 0,
                "z": 62
            },
            "stack_count": 1,
            "market_value": 840.0,
            "is_forbidden": false,
            "quality": -1,
            "hit_points": 0,
            "max_hit_points": 0
            }
        ],
        "mass_usage": 0.75,
        "mass_capacity": 28.0,
        "forageability": "Forageable",
        "visibility": "0.16"
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-13T11:01:59.5952054Z"
}

GET


/api/v1/world/settlements

¶

Возвращает список всех постоянных поселений (баз) на карте мира. Сюда входят колонии игрока и базы других фракций. Полезно для поиска торговых партнеров или целей для рейдов.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/world/settlements

Response:

{
    "success": true,
    "data": [
        {
            "id": 0,
            "name": "Planeton",
            "tile": 2241,
            "faction": {
                "load_id": 0,
                "def_name": "OutlanderCivil",
                "name": "Dinium",
                "is_player": false,
                "leader_title": "Spiritual Bodhisattva",
                "leader_id": 10
            }
        },
        {
            "id": 1,
            "name": "Borne",
            "tile": 1031,
            "faction": {
                "load_id": 1,
                "def_name": "TribeCivil",
                "name": "Union of Cheñoalo",
                "is_player": false,
                "leader_title": "Anima Chief",
                "leader_id": 19
            }
        },
        {
            "id": 2,
            "name": "Carsium",
            "tile": 387,
            "faction": {
                "load_id": 2,
                "def_name": "Empire",
                "name": "Imperium of God",
                "is_player": false,
                "leader_title": "High Stellarch",
                "leader_id": 25
            }
        },
            {
            "id": 3,
            "name": "Colony",
            "tile": 232,
            "faction": {
                "load_id": 14,
                "def_name": "PlayerColony",
                "name": "New Arrivals",
                "is_player": true,
                "leader_title": "Spirit Curate",
                "leader_id": 0
            }
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-13T11:02:36.2212158Z"
}

GET


/api/v1/world/sites

¶

Возвращает список временных объектов мира. Сюда входят места выполнения квестов, лагеря бандитов, тайники с предметами, засады и другие локации, созданные событиями.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/world/sites

Response:

{
    "success": true,
    "data": [
        {
            "id": 12,
            "name": "outpost",
            "tile": 712,
            "faction": {
                "load_id": 7,
                "def_name": "PirateWaster",
                "name": "Gas Crew",
                "is_player": false,
                "leader_title": "Moral Thug",
                "leader_id": 59
            }
        },
        {
            "id": 13,
            "name": "bandit camp",
            "tile": 2720,
            "faction": {
                "load_id": 7,
                "def_name": "PirateWaster",
                "name": "Gas Crew",
                "is_player": false,
                "leader_title": "Moral Thug",
                "leader_id": 59
            }
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-13T11:04:31.8428299Z"
}

GET


/api/v1/world/tile

¶

Возвращает подробную экологическую и географическую информацию о конкретном секторе мира (tile) на основе его ID. Возвращает данные о биоме, температуре, высоте над уровнем моря, а также о дорогах и реках.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/world/tile?id=12345"

Response:

{
    "success": true,
    "data": {
        "id": 232,
        "biome": "Tundra",
        "elevation": 1592.0,
        "temperature": -4.1,
        "rainfall": 269.0,
        "hilliness": "SmallHills",
        "roads": [
            "DirtRoad",
            "DirtRoad"
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-13T11:05:29.488063Z"
}

GET


/api/v1/world/caravan/path

¶

Возвращает текущий статус перемещения и запланированный путь для конкретного каравана в мире.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/world/caravan/path?caravan_id=12"

Response:

{
    "success": true,
    "data": {
        "id": 12,
        "moving": true,
        "current_tile": 150,
        "next_tile": 151,
        "progress": 0.45,
        "destination_tile": 180,
        "path": [
            151,
            152,
            160,
            180
        ]
    },
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/world/player/settlements

¶

Возвращает список всех поселений, принадлежащих фракции игрока.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/world/player/settlements

Response:

{
    "success": true,
    "data": [
        {
            "id": 123,
            "name": "Player's Hope",
            "tile": 5678,
            "faction": {
                "load_id": 3,
                "def_name": "PlayerColony",
                "name": "New Arrivals",
                "is_player": true
            }
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2026-01-04T12:00:00.000Z"
}

GET


/api/v1/world/grid/area

¶

Возвращает список секторов мира в пределах заданного радиуса от центрального сектора.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/world/grid/area?tile_id=12345&radius=5'

Response:

{
    "success": true,
    "data": [
        {
            "id": 12345,
            "biome": "Tundra",
            "elevation": 100.0,
            "temperature": -10.0,
            "rainfall": 200.0,
            "hilliness": "SmallHills",
            "roads": [],
            "rivers": [],
            "lat": 60.0,
            "lon": -30.0,
            "is_polluted": false,
            "pollution": 0.0
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2026-01-04T12:00:00.000Z"
}

GET


/api/v1/world/tile/coordinates

¶

Возвращает широту и долготу для конкретного ID сектора.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/world/tile/coordinates?id=12345'

Response:

{
    "success": true,
    "data": {
        "lat": 60.0,
        "lon": -30.0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2026-01-04T12:00:00.000Z"
}

GET


/api/v1/world/tile/details

¶

Возвращает подробную информацию о конкретном секторе.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/world/tile/details?id=12345'

Response:

{
    "success": true,
    "data": {
        "id": 12345,
        "biome": "Tundra",
        "elevation": 100.0,
        "temperature": -10.0,
        "rainfall": 200.0,
        "hilliness": "SmallHills",
        "roads": [
            "279644:StoneRoad",
            "279641:StoneRoad"
        ],
        "rivers": [
            "279640:Creek",
            "279686:Creek"
        ],
        "lat": 60.0,
        "lon": -30.0,
        "is_polluted": false,
        "pollution": 0.0,
        "time_zone": "2",
        "forageability": 0.5,
        "growing_period": "Year-round",
        "movement_difficulty": 1.0,
        "stone_types": [
            "Sandstone",
            "Granite"
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2026-01-04T12:00:00.000Z"
}

GET


/api/v1/world/grid

¶

Возвращает всю сетку мира, предоставляя список всех секторов с их основной информацией.

Example:

curl --request GET \
--url http://localhost:8765/api/v1/world/grid

Response:

{
    "success": true,
    "data": [
        {
            "id": 0,
            "biome": "Ocean",
            "elevation": -100.0,
            "temperature": 10.0,
            "rainfall": 500.0,
            "hilliness": "Flat",
            "roads": [
                "279644:StoneRoad",
                "279641:StoneRoad"
            ],
            "rivers": [
                "279640:Creek",
                "279686:Creek"
            ],
            "lat": -90.0,
            "lon": 0.0,
            "is_polluted": false,
            "pollution": 0.0
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2026-01-04T12:00:00.000Z"
}

Строительство¶

Контроллер Builder Controller предоставляет инструменты для программного построения и деконструкции. Он позволяет копировать, вставлять и создавать чертежи областей карты.

POST


/api/v1/builder/copy

¶

Скопировать указанную область карты, включая здания, объекты и местность. Скопированные данные можно использовать для вставки через /api/v1/builder/paste.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/builder/copy \
--header 'content-type: application/json' \
--data '{
    "from": { "x": 100, "z": 100 },
    "to": { "x": 110, "z": 110 }
}'

Response:

{
    "map_id": 0,
    "point_a": {"x": 10, "y": 0, "z": 10},
    "point_b": {"x": 16, "y": 0, "z": 16}
}

Response:

{
    "success":true,
    "data": {
        "width":7,
        "height":7,
        "floors": [
            {"def_name":"Concrete","rel_x":1,"rel_z":1},
            {"def_name":"Concrete","rel_x":3,"rel_z":2}],
        "buildings": [
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":3,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":1,"rotation":0},
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:15:20.9851409Z"
}

POST


/api/v1/builder/paste

¶

Вставить ранее скопированную область в новое место на карте.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/builder/paste \
--header 'content-type: application/json' \
--data '{
    "at": { "x": 150, "z": 150 }
}'

Request:

{
    "map_id": 0,
    "position": {"x": 80, "y": 0, "z": 80},
    "blueprint": {
        "width":7,
        "height":7,
        "floors": [
            {"def_name":"Concrete","rel_x":1,"rel_z":1},
            {"def_name":"Concrete","rel_x":3,"rel_z":2}],
        "buildings": [
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":3,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":1,"rotation":0},
        ]
    },
    "clear_obstacles": true,
}

Response:

{
    "success":true,
    "errors":[],
    "warnings":[],
    "timestamp":"2025-12-31T12:18:40.2019606Z"
}

POST


/api/v1/builder/check-zone

¶

Проверяет, можно ли создать зону в заданных ячейках, не совершая фактического создания. Возвращает количество свободных, занятых и выходящих за границы карты ячеек.

Пример:

curl --request POST \
--url http://localhost:8765/api/v1/builder/check-zone \
--header 'content-type: application/json' \
--data '{
    "map_id": 0,
    "point_a": {"x": 50, "y": 0, "z": 50},
    "point_b": {"x": 55, "y": 0, "z": 55}
}'

Запрос:

{
    "map_id": 0,
    "point_a": {"x": 50, "y": 0, "z": 50},
    "point_b": {"x": 55, "y": 0, "z": 55}
}

Ответ:

{
    "success": true,
    "data": {
        "free_cells": 30,
        "occupied_cells": 6,
        "out_of_bounds_cells": 0,
        "can_create": true
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-31T12:18:40.2019606Z"
}

POST


/api/v1/builder/blueprint

¶

Вставляет постройку в виде чертежа, создавая задание для поселенцев.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/builder/blueprint \
--header 'content-type: application/json' \
--data '{
    "at": { "x": 150, "z": 150 }
}'

Request:

{
    "map_id": 0,
    "position": {"x": 80, "y": 0, "z": 80},
    "blueprint": {
        "width":7,
        "height":7,
        "floors": [
            {"def_name":"Concrete","rel_x":1,"rel_z":1},
            {"def_name":"Concrete","rel_x":3,"rel_z":2}],
        "buildings": [
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":3,"rel_z":0,"rotation":0},
            {"def_name":"Wall","stuff_def_name":"WoodLog","rel_x":0,"rel_z":1,"rotation":0},
        ]
    },
}

Response:

{
    "success":true,
    "errors":[],
    "warnings":[],
    "timestamp":"2025-12-31T12:18:40.2019606Z"
}

🌍 Map & Environment API¶

Map Controller¶

GET /api/v1/map/things ¶

GET /api/v1/maps ¶

GET /api/v1/map/pawns ¶

GET /api/v1/map/terrain ¶

GET /api/v1/map/things-at ¶

GET /api/v1/map/things/radius ¶

GET /api/v1/map/ore ¶

GET /api/v1/map/fog-grid ¶

GET /api/v1/map/plants ¶

GET /api/v1/map/weather ¶

GET /api/v1/map/animals ¶

GET /api/v1/map/zones ¶

GET /api/v1/map/building/info ¶

POST /api/v1/map/weather/change ¶

GET /api/v1/map/power/info ¶

GET /api/v1/map/creatures/summary ¶

GET /api/v1/map/farm/summary ¶

POST /api/v1/map/zone/growing ¶

GET /api/v1/map/rooms ¶

GET /api/v1/map/buildings ¶

POST /api/v1/map/destroy/corpses ¶

POST /api/v1/map/destroy/forbidden ¶

POST /api/v1/map/destroy/rect ¶

POST /api/v1/map/repair/positions ¶

POST /api/v1/map/repair/rect ¶

POST /api/v1/map/droppod ¶

POST /api/v1/map/zone/stockpile ¶

POST /api/v1/map/zone/stockpile/update ¶

DELETE /api/v1/map/zone/stockpile/delete ¶

POST /api/v1/map/building/power ¶

GET /api/v1/datetime ¶

GET /api/v1/datetime/tile ¶

Глобальная карта¶

GET /api/v1/world/caravans ¶

GET /api/v1/world/settlements ¶

GET /api/v1/world/sites ¶

GET /api/v1/world/tile ¶

GET /api/v1/world/caravan/path ¶

GET /api/v1/world/player/settlements ¶

GET /api/v1/world/grid/area ¶

GET /api/v1/world/tile/coordinates ¶

GET /api/v1/world/tile/details ¶

GET /api/v1/world/grid ¶

Строительство¶

POST /api/v1/builder/copy ¶

POST /api/v1/builder/paste ¶

POST /api/v1/builder/check-zone ¶

POST /api/v1/builder/blueprint ¶

GET

`/api/v1/map/things` ¶

GET

`/api/v1/maps` ¶

GET

`/api/v1/map/pawns` ¶

GET

`/api/v1/map/terrain` ¶

GET

`/api/v1/map/things-at` ¶

GET

`/api/v1/map/things/radius` ¶

GET

`/api/v1/map/ore` ¶

GET

`/api/v1/map/fog-grid` ¶

GET

`/api/v1/map/plants` ¶

GET

`/api/v1/map/weather` ¶

GET

`/api/v1/map/animals` ¶

GET

`/api/v1/map/zones` ¶

GET

`/api/v1/map/building/info` ¶

POST

`/api/v1/map/weather/change` ¶

GET

`/api/v1/map/power/info` ¶

GET

`/api/v1/map/creatures/summary` ¶

GET

`/api/v1/map/farm/summary` ¶

POST

`/api/v1/map/zone/growing` ¶

GET

`/api/v1/map/rooms` ¶

GET

`/api/v1/map/buildings` ¶

POST

`/api/v1/map/destroy/corpses` ¶

POST

`/api/v1/map/destroy/forbidden` ¶

POST

`/api/v1/map/destroy/rect` ¶

POST

`/api/v1/map/repair/positions` ¶

POST

`/api/v1/map/repair/rect` ¶

POST

`/api/v1/map/droppod` ¶

POST

`/api/v1/map/zone/stockpile` ¶

POST

`/api/v1/map/zone/stockpile/update` ¶

DELETE

`/api/v1/map/zone/stockpile/delete` ¶

POST

`/api/v1/map/building/power` ¶

GET

`/api/v1/datetime` ¶

GET

`/api/v1/datetime/tile` ¶

GET

`/api/v1/world/caravans` ¶

GET

`/api/v1/world/settlements` ¶

GET

`/api/v1/world/sites` ¶

GET

`/api/v1/world/tile` ¶

GET

`/api/v1/world/caravan/path` ¶

GET

`/api/v1/world/player/settlements` ¶

GET

`/api/v1/world/grid/area` ¶

GET

`/api/v1/world/tile/coordinates` ¶

GET

`/api/v1/world/tile/details` ¶

GET

`/api/v1/world/grid` ¶

POST

`/api/v1/builder/copy` ¶

POST

`/api/v1/builder/paste` ¶

POST

`/api/v1/builder/check-zone` ¶

POST

`/api/v1/builder/blueprint` ¶