⚙️ Game State & Mechanics API¶

This section handles the core game lifecycle (save/load/pause), triggering random events, managing factions, and research.

Игра¶

Этот контроллер обрабатывает общие игровые функции.

GET


/api/v1/game/state

¶

Возвращает текущее состояние игры.

Example:

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

Response:

{
    "success": true,
    "data": {
        "game_tick": 120,
        "colony_wealth": 4.0,
        "colonist_count": 3,
        "storyteller": "Cassandra",
        "is_paused": true
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:39:28.6476222Z"
}

POST


/api/v1/game/speed

¶

Устанавливает текущую скорость игрового времени.

Info

Значения скорости:

`0`: Пауза
`1`: Обычная скорость
`2`: Быстрая скорость
`3`: Очень быстрая скорость
`4`: Ультра-быстрая (только в режиме разработчика)

Example:

curl --request POST \
--url "http://localhost:8765/api/v1/game/speed?speed=3"

Response:

{
    "success": true,
    "data": "Game speed set to 3",
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T14:10:05.123Z"
}

GET


/api/v1/game/settings/run-in-background

¶

Получает текущее состояние настройки «Работа в фоновом режиме».

Example:

curl --request GET \
--url http://localhost:8765/api/v1/game/settings/run-in-background

Response:

{
    "success": true,
    "data": true,
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

POST


/api/v1/game/settings/toggle/run-in-background

¶

Переключает или устанавливает настройку «Работа в фоновом режиме». Тело запроса определяет желаемое состояние.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/game/settings/toggle/run-in-background \
--header 'Content-Type: application/json' \
--data 'true'

Response:

{
    "success": true,
    "data": true,
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/version

¶

Возвращает информацию о версии игры, мода REST API и самого API. Эта конечная точка предоставляет важные идентификационные метаданные, которые могут быть использованы для проверки совместимости, отладки и системной документации.

Example:

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

Response:

{
    "success": true,
    "data": {
        "rim_world_version": "1.5.4243",
        "mod_version": "1.2.0",
        "api_version": "v1"
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T18:52:09.0916968Z"
}

GET


/api/v1/mods/list

¶

Возвращает список всех активных модов с их метаданными.

Пример:

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

Ответ:

{
    "success": true,
    "data": [
        {
            "name": "Core",
            "package_id": "ludeon.rimworld",
            "load_order": 0
        },
        {
            "name": "RIMAPI",
            "package_id": "redeyedev.rimapi",
            "load_order": 1
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T18:53:40.5041431Z"
}

GET


/api/v1/mods/info

¶

Возвращает информацию об установленных модах. Можно отфильтровать по package_id, чтобы получить подробную информацию об одном моде.

Пример (Все моды):

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

Пример (Один мод):

curl --request GET \
--url http://localhost:8765/api/v1/mods/info?package_id=RedEyeDev.RIMAPI

Ответ:

{
    "success": true,
    "data": [
        {
        "name": "RIMAPI",
        "package_id": "RedEyeDev.RIMAPI",
        "load_order": 3,
        "author": "RedEyeDev",
        "description": "RIMAPI is a mod...",
        "url": "https://...",
        "version": "1.9.0",
        "supported_versions": ["1.5", "1.6"],
        "root_dir": "..."
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "..."
}

GET


/api/v1/mods/preview

¶

Возвращает превью-изображение мода в виде строки, закодированной в base64.

Пример:

curl --request GET \
--url http://localhost:8765/api/v1/mods/preview?package_id=RedEyeDev.RIMAPI

Ответ:

{
    "success": true,
    "data": "iVBORw0KGgoAAAANSUhEUgAA...",
    "errors": [],
    "warnings": [],
    "timestamp": "..."
}

POST


/api/v1/mods/configure

¶

Настраивает список активных модов и порядок их загрузки. Передайте массив ID пакетов в том порядке, в котором вы хотите их загрузить. Core (ludeon.rimworld) будет автоматически добавлен в начало, если он отсутствует. Установите restart_game в значение true, чтобы немедленно перезагрузить RimWorld и применить изменения.

Example:

curl --request POST \
  --url http://localhost:8765/api/v1/mods/configure \
  --header 'content-type: application/json' \
  --data '{"package_ids":["brrainz.harmony","ludeon.rimworld","ludeon.rimworld.royalty","ludeon.rimworld.ideology","ludeon.rimworld.biotech","ludeon.rimworld.anomaly","ludeon.rimworld.odyssey","unlimitedhugs.hugslib","redeyedev.rimapi"],"restart_game":true}'

Request Body:

{
  "package_ids": [
    "brrainz.harmony",
    "ludeon.rimworld",
    "ludeon.rimworld.royalty",
    "ludeon.rimworld.ideology",
    "ludeon.rimworld.biotech",
    "ludeon.rimworld.anomaly",
    "ludeon.rimworld.odyssey",
    "unlimitedhugs.hugslib",
    "redeyedev.rimapi"
  ],
  "restart_game": true
}

Response:

{
    "success": true,
    "data": null,
    "errors": [],
    "warnings": [],
    "timestamp": "2026-02-18T18:23:32.0000000Z"
}

POST


/api/v1/select

¶

Выбирает конкретный игровой объект (поселенца, здание, предмет и т. д.) на основе его типа и уникального идентификатора.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/select?type=pawn&id=443'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

POST


/api/v1/deselect

¶

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

Example:

curl --request POST \
--url http://localhost:8765/api/v1/deselect

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

POST


/api/v1/open-tab

¶

Открывает определенную панель информации (вкладку) для выбранного в данный момент поселенца в окне осмотра игры. Эта конечная точка позволяет внешне просматривать подробную информацию о здоровье, снаряжении, потребностях, отношениях и других атрибутах поселенца — дублируя интерфейс вкладок, доступный при ручном осмотре персонажа в игре.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/open-tab?name=health'

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

GET


/api/v1/def/all

¶

Возвращает исчерпывающую информацию обо всех записях определений игры (defs) из системы данных RimWorld. Определения — это основные структуры данных, которые определяют почти каждый элемент в игре, включая предметы, здания, существ, ландшафт, исследовательские проекты и многое другое.

Info

Things Defs

Example

{
    "def_name": "Beer",
    "label": "beer",
    "description": "The first beverage besides water ever consumed by mankind. Beer can taste good, but its main effect is intoxication. Excessive consumption can lead to alcohol blackouts and, over time, addiction.",
    "category": "Item",
    "thing_class": "ThingWithComps",
    "stat_base": {
    "max_hit_points": 50.0,
    "flammability": 0.5,
    "deterioration_rate": 0.5,
    "beauty": -4.0,
    "market_value": 12.0,
    "mass": 0.3,
    "nutrition": 0.08
    },
    "is_weapon": true,
    "is_apparel": false,
    "is_item": true,
    "is_pawn": false,
    "is_plant": false,
    "is_building": false,
    "is_medicine": false,
    "is_drug": true,
    "market_value": 12.0,
    "mass": 0.3,
    "max_hit_points": 50.0,
    "flammability": 0.5,
    "stack_limit": 25,
    "nutrition": 0.08,
    "work_to_make": 1.0,
    "work_to_build": 1.0,
    "beauty": -4.0,
    "max_health": 0.0,
    "armor_rating__sharp": 0.0,
    "armor_rating__blunt": 0.0,
    "armor_rating__heat": 0.0,
    "insulation__cold": 0.0,
    "insulation__heat": 0.0
}

Incidents Defs

Example

{
    "def_name": "BloodRain",
    "label": "Blood rain",
    "base_chance": 0.5,
    "base_chance_with_royalty": -1.0,
    "letter_def_name": "ThreatBig",
    "population_effect": "0",
    "min_population": 0,
    "min_threat_points": -3.40282347E+38,
    "max_threat_points": 3.40282347E+38,
    "category": "ThreatBig",
    "should_ignore_recent_weighting": false,
    "tags": [],
    "disallowed_biomes": [],
    "allowed_biomes": [],
    "require_colonists_present": false
},

Conditions Defs
PawnKind Defs
Trait Defs
Research Defs
Hediff Defs

Example

{
    "def_name": "GoJuiceHigh",
    "label": "High on go-juice",
    "description": "Go-juice in the bloodstream. It supercharges combat-related abilities, and instantly increases psyfocus when first injected.",
    "hediff_class": "Hediff_High",
    "is_addiction": false,
    "makes_sick_thought": false,
    "severity_per_day": 0.0,
    "max_severity": 1.0,
    "tendable": false,
    "is_bad": false,
    "stages": [
    {
        "min_severity": 0.0,
        "death_mtb_days": -1.0,
        "pain_factor": 0.1,
        "forget_memory_thought_mtb_days": -1.0,
        "vomit_mtb_days": -1.0,
        "mental_break_mtb_days": -1.0
    }
    ]
}

Skill Defs
WorkType Defs
Need Defs
Thought Defs
Stat Defs
WorldObject Defs
Biome Defs
Terrain Defs
Recipe Defs
Body Defs
BodyPart Defs
Faction Defs
Sound Defs
DesignationCategory Defs
JoyKind Defs
Meme Defs
Precept Defs
Ability Defs
Gene Defs
Weather Defs
RoomRole Defs
RoomStat Defs
MentalState Defs
DrugPolicy Defs
Plant Defs
Animal Defs
Storyteller Defs

Example

{
    "def_name": "Cassandra"
},
{
    "def_name": "Phoebe"
},
{
    "def_name": "Randy"
},
{
    "def_name": "Tutor"
}

Difficulty Defs

Example

{
    "def_name": "Peaceful"
},
{
    "def_name": "Easy"
},
{
    "def_name": "Medium"
},
{
    "def_name": "Rough"
},
{
    "def_name": "Hard"
},
{
    "def_name": "Extreme"
},
{
    "def_name": "Custom"
}

Example:

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

Response:

{
    "success": true,
    "data": {
        "things_defs": [
            {
                "def_name": "TextBook",
                "label": "textbook",
                "description": "A book which focuses on teaching skills.",
                "category": "Item",
                "thing_class": "Book",
                "stat_base": {
                "max_hit_points": 60.0,
                "deterioration_rate": 5.0,
                "mass": 0.5,
                "flammability": 1.0,
                "beauty": 1.0,
                "market_value": 160.0
                },
                "is_weapon": false,
                "is_apparel": false,
                "is_item": true,
                "is_pawn": false,
                "is_plant": false,
                "is_building": false,
                "is_medicine": false,
                "is_drug": false,
                "market_value": 160.0,
                "mass": 0.5,
                "max_hit_points": 60.0,
                "flammability": 1.0,
                "stack_limit": 1,
                "nutrition": 0.0,
                "work_to_make": 1.0,
                "work_to_build": 1.0,
                "beauty": 1.0,
                "max_health": 0.0,
                "armor_rating__sharp": 0.0,
                "armor_rating__blunt": 0.0,
                "armor_rating__heat": 0.0,
                "insulation__cold": 0.0,
                "insulation__heat": 0.0
            },
            {
                <...>
            }
        ],
        "incidents_defs": [],
        "conditions_defs": [],
        "pawn_kind_defs": [],
        "trait_defs": [],
        "research_defs": [],
        "hediff_defs": [],
        "skill_defs": [],
        "work_type_defs": [],
        "need_defs": [],
        "stat_defs": [],
        "world_object_defs": [],
        "biome_defs": [],
        "terrain_defs": [],
        "recipe_defs": [],
        "body_defs": [],
        "body_part_defs": [],
        "faction_defs": [],
        "sound_defs": [],
        "designation_category_defs": [],
        "joy_kind_defs": [],
        "meme_defs": [],
        "precept_defs": [],
        "ability_defs": [],
        "gene_defs": [],
        "weather_defs": [],
        "room_role_defs": [],
        "room_stat_defs": [],
        "mental_state_defs": [],
        "drug_policy_defs": [],
        "plant_defs": [],
        "animal_defs": [],
        "job_defs": []
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:09:46.047553Z"
}

POST


/api/v1/game/select-area

¶

Имитирует действие выделения рамкой в игровом мире (UI). Выбирает все выделяемые объекты (поселенцев, предметы и т. д.) внутри прямоугольника, заданного PositionA и PositionB.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/game/select-area \
--header 'Content-Type: application/json' \
--data '{
    "position_a": { "x": 10, "y": 0, "z": 10 },
    "position_b": { "x": 20, "y": 0, "z": 20 }
}'

Request Body:

{
    "position_a": { "x": 10, "y": 0, "z": 10 },
    "position_b": { "x": 20, "y": 0, "z": 20 }
}

Response:

{
    "success": true,
    "data": "Area selected from (10, 0, 10) to (20, 0, 20). 5 objects selected.",
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-14T14:18:10.000Z"
}

POST


/api/v1/game/send/letter

¶

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

Example:

curl --request POST \
--url http://localhost:8765/api/v1/game/send/letter

Request:

{
    "label": "New Message Label",
    "message": "Hello RimWorld!",
    "letter_def": "NeutralEvent"
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

POST


/api/v1/game/save

¶

Сохраняет текущее состояние игры в файл с указанным именем.

Example:

curl --request POST \
--url "http://localhost:8765/api/v1/game/save?name=MyApiSave"

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-20T10:00:00.000Z"
}

POST


/api/v1/game/load

¶

Пытается загрузить состояние игры из файла сохранения с указанным именем.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/game/load?name=MyApiSave"

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-20T10:01:00.000Z"
}

POST


/api/v1/game/start/devquick

¶

Немедленно запускает новую игру, используя конфигурацию разработчика «быстрый старт», минуя выбор персонажей и места высадки. Это полезно для быстрого тестирования.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/game/start/devquick

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-20T10:02:00.000Z"
}

POST


/api/v1/game/start

¶

Эта конечная точка запускает новую игру RimWorld с указанными параметрами конфигурации. Она инициализирует новый игровой мир с заданным рассказчиком, сложностью, настройками карты и параметрами генерации планеты.

Получение доступных опций

Имена рассказчиков, уровни сложности и другие значения определений можно получить из конечной точки /api/v1/def/all. Эта конечная точка предоставляет исчерпывающую информацию обо всех игровых определениях, включая:

Определения рассказчиков
Настройки сложности

Пример использования:

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

Ответ представляет собой большую структуру JSON из игры, она содержит категоризированные определения, которые можно использовать для заполнения параметров этого запроса на запуск игры.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/game/start \
--header 'Content-Type: application/json' \
--data '{
    "storyteller_name": "Randy",
    "difficulty_name": "Peaceful",
    "map_size": 120,
    "permadeath": false,
    "planet_coverage": 0.1,
    "world_seed": "rickroll",
    "starting_tile": "7298",
    "starting_season": "2",
    "overall_rainfall": 2,
    "overall_temperature": 2,
    "overall_population": 2,
    "landmark_density": 2
}'

Request:

{
    "storyteller_name": "Randy",
    "difficulty_name": "Peaceful",
    "map_size": 120,
    "permadeath": false,
    "planet_coverage": 0.1,
    "world_seed": "rickroll",
    "starting_tile": "7298",
    "starting_season": "2",
    "overall_rainfall": 2,
    "overall_temperature": 2,
    "overall_population": 2,
    "landmark_density": 2
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-20T10:03:00.000Z"
}

GET


/api/v1/game/settings

¶

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

Example:

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

Response:

{
    "success": true,
    "data": {
        "language": "English",
        "run_in_background": true,
        "development_mode": true,
        "log_verbose": false,
        "temperature_mode": "Celsius",
        "autosave_interval": true,
        "resolution": "1024x768",
        "fullscreen": false,
        "user_interface_scale": 1.0,
        "custom_cursor_enabled": true,
        "hats_only_on_map": false,
        "plant_wind_sway": true,
        "max_number_of_player_settlements": 1,
        "volume_master": 0.6375921,
        "volume_game": 0.7051597,
        "volume_music": 0.0,
        "volume_ambient": 0.6007371,
        "pause_on_load": false,
        "pause_on_urgent_letter": "MajorThreat",
        "automatic_pause_on_letter": false,
        "edge_screen_scroll": true,
        "map_drag_sensitivity": 1.3,
        "zoom_to_mouse": false,
        "show_realtime_clock": true,
        "resource_readout_categorized": false,
        "show_animal_names": false,
        "reset_mods_config_on_crash": false,
        "texture_compression": 0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-20T12:30:35.4174593Z"
}

POST


/api/v1/game/main-menu

¶

Завершает текущую игровую сессию и возвращает игрока в главное меню. Операция выполняется безопасно в основном потоке Unity.

Пример:

curl --request POST \
--url 'http://localhost:8765/api/v1/game/main-menu'

Ответ:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:39:28.6476222Z"
}

POST


/api/v1/game/quit

¶

Полностью завершает работу приложения RimWorld и выходит на рабочий стол.

Пример:

curl --request POST \
--url 'http://localhost:8765/api/v1/game/quit'

Ответ:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:39:28.6476222Z"
}

Игровые события¶

Game Events Controller позволяет внешним системам выступать в роли «Рассказчика», принудительно вызывая определенные инциденты немедленно.

Управление повествованием

Это полезно для интеграций с Twitch или менеджеров сценариев, которые хотят запускать рейды, изменения погоды или сброс капсул по запросу.

Поддерживаемые типы событий:

Угрозы: Рейды, животные-людоеды, заражения.
Погода: Дождь, туман, затмения, солнечные вспышки.
Разное: Прибытие торговцев, запуск квестов.

GET


/api/v1/quests

¶

Возвращает список всех активных и завершенных квестов.

Example:

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

Response:

{
    "success": true,
    "data": {
        "active_quests": [
        {
            "id": 1,
            "quest_def": "OpportunitySite_ItemStash",
            "name": "Choma's Shack of Valuables",
            "description": "<color=#D09B61FF>Choma</color>, Great Chief of <color=#00BFFFFF>Coalition of Tol</color>, has informed us of a collection of valuable items worth $535 not far from us. The collection consists of:\n\n  - The Archaic Psychoid Chronicle (excellent)\r\n  - Voro-Harbinger (good)\n\n<color=#D09B61FF>Choma</color> says that there may be an <color=#D46F68FF>unknown threat</color>.",
            "state": "Ongoing",
            "expiry_hours": -0.000400000019,
            "reward": [
            "Reward_Items(value $535)\n  -Voro-Harbinger (good) $310\n  -The Archaic Psychoid Chronicle (excellent) $225"
            ]
        }
        ],
        "historical_quests": [
        {
            "id": 0,
            "quest_def": "Beggars",
            "name": "Drifter Hopes for Resources",
            "description": "A poor traveler named <color=#D09B61FF>Ace</color> is approaching looking for help. <color=#D09B61FF>Ace</color> is begging for x700 silver. <color=#D09B61FF>Ace</color> wants the silver to pay off a debt to a gang of pirates who are hunting her.\n\nYou can give items to <color=#D09B61FF>Ace</color> by selecting a colonist and right-clicking on her.\n\n<color=#D09B61FF>Ace</color> will move on after <color=#87F6F6FF>1 day</color>.\n\nThis traveler is not part of any faction. If you wish, you can choose to kill, arrest, sell, or harvest her, without diplomatic consequences.",
            "state": "EndedSuccess",
            "expiry_hours": -0.000400000019,
            "reward": []
        }
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:43:32.2659508Z"
}

GET


/api/v1/incidents

¶

Возвращает список произошедших инцидентов.

Example:

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

Response:

{
    "success": true,
    "data": {
        "incidents": [
            {
                "incident_def": "VisitorGroup",
                "label": "visitor group",
                "category": "None",
                "incident_hour": 60.0,
                "days_since_occurred": 0.1068
            },
            {
                "incident_def": "GiveQuest_Beggars",
                "label": "beggars arrive",
                "category": "GiveQuest",
                "incident_hour": 8.8,
                "days_since_occurred": 2.24013329
            }
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:24:31.91622Z"
}

GET


/api/v1/lords

¶

Возвращает подробную информацию обо всех активных процессах «Lord» на указанной карте. В RimWorld «Lord» представляет собой высокоуровневый менеджер ИИ, который координирует группы существ для достижения общей цели — такой, как рейд, посещение или торговля.

Example:

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

Response:

{
    "success": true,
    "data": [
        {
            "load_id": 2,
            "faction_name": "Nation of Iralaguaro",
            "faction_def_name": "TribeCivil",
            "lord_job_type": "LordJob_VisitColony",
            "current_toil_name": "LordToil_DefendPoint",
            "ticks_in_toil": 2231,
            "num_pawns_lost_violently": 0,
            "num_pawns_ever_gained": 1,
            "owned_pawn_ids": [
                "Human8834"
            ],
            "owned_building_ids": [],
            "any_active_pawn": true
        },
        {
            "load_id": 3,
            "faction_name": "Cancer Unit",
            "faction_def_name": "PirateWaster",
            "lord_job_type": "LordJob_StageThenAttack",
            "current_toil_name": "LordToil_Stage",
            "ticks_in_toil": 0,
            "num_pawns_lost_violently": 0,
            "num_pawns_ever_gained": 1,
            "owned_pawn_ids": [
                "Human8861"
            ],
            "owned_building_ids": [],
            "any_active_pawn": true
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-10T19:26:22.0370532Z"
}

GET


/api/v1/incidents/top

¶

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

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/incidents/top?limit=3"

Response:

{
    "success": true,
    "data": [
        {
            "def_name": "RaidEnemy",
            "label": "enemy raid",
            "category": "ThreatBig",
            "current_weight": 1.2
        },
        {
            "def_name": "TraderCaravan",
            "label": "trader caravan",
            "category": "Misc",
            "current_weight": 0.85
        },
        {
            "def_name": "TravelerGroup",
            "label": "travelers",
            "category": "Misc",
            "current_weight": 0.5
        }
    ],
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

GET


/api/v1/incident/chance

¶

Вычисляет конкретный вес вероятности для одного определения инцидента.

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/incident/chance?incident_def_name=RaidEnemy"

Request Body (or Query Params):

{
    "incident_def_name": "RaidEnemy"
}

Response:

{
    "success": true,
    "data": {
        "value": 1.2
    },
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

POST


/api/v1/incident/trigger

¶

Вручную немедленно запускает определенный игровой инцидент (событие).

Example:

curl --request POST \
--url http://localhost:8765/api/v1/incident/trigger \
--header 'content-type: application/json' \
--data '{
    "name": "RaidEnemy",
    "map_id": "0",
    "incident_parms": {
        "points": 300.0,
        "forced": true,
        "faction": "Pirate",
        "send_letter": true,
        "custom_letter_label": "API Raid Test",
        "custom_letter_text": "Test raid triggered via API"
    }
}'

Request:

{
    "name": "RaidEnemy",
    "map_id": "0",
    "incident_parms": {
        "points": 300.0,
        "forced": true,
        "faction": "Pirate",
        "send_letter": true,
        "custom_letter_label": "API Raid Test",
        "custom_letter_text": "Test raid triggered via API"
    }
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

Фракции¶

Faction Controller управляет геополитическим ландшафтом мира. Он позволяет проверять и манипулировать отношениями между колонией игрока и другими группами.

Ключевые функции:

Дипломатия: Настройка доброй воли и статуса отношений (Враждебный/Нейтральный/Союзник).
Реестр: Список всех созданных фракций и их лидеров.
Взаимодействие: Инициирование специфических для фракции запросов или подарков.

GET


/api/v1/factions

¶

Возвращает список всех фракций, известных в настоящее время в игровом мире.

Example:

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

Response:

{
    "success": true,
    "data": [
        {
            "load_id": 0,
            "def_name": "OutlanderCivil",
            "name": "Western Haderia",
            "is_player": false,
            "relation": "Neutral",
            "goodwill": 0
        },
        {
            "load_id": 1,
            "def_name": "TribeCivil",
            "name": "Coalition of Tol",
            "is_player": false,
            "relation": "Neutral",
            "goodwill": 0
        },
        {
            "load_id": 2,
            "def_name": "Empire",
            "name": "Empire of Mophoos",
            "is_player": false,
            "relation": "Neutral",
            "goodwill": 0
        },
        {
            "load_id": 3,
            "def_name": "PlayerColony",
            "name": "New Arrivals",
            "is_player": true,
            "relation": "",
            "goodwill": 0
        }
    ],
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:21:17.8272328Z"
}

GET


/api/v1/faction/relations

¶

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

curl --request GET \
--url http://localhost:8765/api/v1/faction/relations?id=2

{
    "label": "lowercase label",
    "message": "uppercase message",
    "letter_def": "NeutralEvent"
}

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

GET


/api/v1/faction/player

¶

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

Example:

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

Response:

{
    "success": true,
    "data": {
        "load_id": 3,
        "def_name": "PlayerColony",
        "name": "New Arrivals",
        "is_player": true,
        "leader_title": "Spirit Speaker",
        "leader_id": 0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:22:33.5209596Z"
}

GET


/api/v1/faction

¶

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

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/faction?id=2'

Response:

{
    "success": true,
    "data": {
        "load_id": 2,
        "def_name": "Empire",
        "name": "Empire of Mophoos",
        "is_player": false,
        "leader_title": "High Stellarch",
        "leader_id": 969
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:23:10.8428989Z"
}

GET


/api/v1/faction/relation-with

¶

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

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/faction/relation-with?id=2&other_id=1'

Response:

{
    "success": true,
    "data": {
        "goodwill": 0,
        "relation_kind": "Neutral"
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:25:02.2515491Z"
}

GET


/api/v1/faction/def

¶

Извлекает необработанные данные определения (Def) для фракции.

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/faction/def?name=OutlanderCivil'

Response:

{
    "success": true,
    "data": {
        "def_name": "OutlanderCivil",
        "pawn_singular": "outlander",
        "pawns_plural": "outlanders",
        "leader_title": "prime councilor",
        "category_tag": "Outlander",
        "hostile_to_factionless_humanlikes": false,
        "starting_count_at_world_creation": "1",
        "permanent_enemy": false,
        "natural_enemy": false,
        "classic_ideo": true,
        "hidden_ideo": false,
        "can_siege": true,
        "can_stage_attacks": true,
        "can_use_avoid_grid": true,
        "can_psychic_ritual_siege": false,
        "earliest_raid_days": 0.0
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:34:20.6487856Z"
}

POST


/api/v1/faction/change/goodwill

¶

Вручную изменяет значение доброй воли между двумя фракциями на указанную величину.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/faction/change/goodwill \
--header 'content-type: application/json' \
--data '{
    "id": 0,
    "other_id": 2,
    "value": -30,
    "send_message": false,
    "can_send_hostility_letter": false
}'

Request:

{
    "id": 0,
    "other_id": 2,
    "value": -30,
    "send_message": false,
    "can_send_hostility_letter": false
}

Response:

{
    "success": true,
    "data": {
        "goodwill": 0,
        "relation_kind": "Neutral"
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-11T19:25:02.2515491Z"
}

GET


/api/v1/faction/icon

¶

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

Example:

curl --request GET \
--url "http://localhost:8765/api/v1/faction/icon?id=12"

Response:

{
    "success": true,
    "data": {
        "image": {
            "result": "Success",
            "image_base_64": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AA..."
        },
        "color": "#9A2A2A"
    },
    "timestamp": "2025-12-11T19:46:05.7088803Z"
}

POST


/api/v1/faction/goodwill

¶

Устанавливает значение доброй воли между двумя фракциями.

Example:

curl --request POST \
--url http://localhost:8765/api/v1/faction/goodwill \
--header 'content-type: application/json' \
--data '{
    "id": 0,
    "other_id": 2,
    "value": 50
}'

Request:

{
    "id": 0,
    "other_id": 2,
    "value": 50
}

Response:

{
    "success": true,
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-08T19:13:29.997162Z"
}

Исследования¶

Управляет научным прогрессом колонии. Этот контроллер позволяет просматривать текущее состояние дерева технологий и мгновенно разблокировать технологии.

GET


/api/v1/research/progress

¶

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

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/research/progress'

Response:

{
    "success": true,
    "data": {
        "name": "Microelectronics",
        "label": "Microelectronics",
        "progress": 500,
        "research_points": 3000,
        "description": "Build advanced components and electronics.",
        "is_finished": false,
        "can_start_now": true,
        "player_has_any_appropriate_research_bench": true,
        "required_analyzed_thing_count": 0,
        "analyzed_things_completed": 0,
        "tech_level": "Industrial",
        "prerequisites": ["Electricity"],
        "hidden_prerequisites": [],
        "required_by_this": ["Fabrication", "AdvancedMachining"],
        "progress_percent": 0.16666667
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-12T10:00:00.0000000Z"
}

GET


/api/v1/research/finished

¶

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

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/research/finished'

Response:

{
    "success": true,
    "data": {
        "finished_projects": [
            "electricity",
            "basic_research",
            "stonecutting"
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-12T10:00:00.0000000Z"
}

GET


/api/v1/research/tree

¶

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

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/research/tree'

Response:

{
    "success": true,
    "data": {
        "projects": [
            {
                "name": "basic_research",
                "label": "basic research",
                "progress": 0,
                "research_points": 500,
                "description": "unlocks basic research capabilities.",
                "is_finished": true,
                "can_start_now": false,
                "player_has_any_appropriate_research_bench": true,
                "required_analyzed_thing_count": 0,
                "analyzed_things_completed": 0,
                "tech_level": "neolithic",
                "prerequisites": [],
                "hidden_prerequisites": [],
                "required_by_this": ["electricity", "stonecutting"],
                "progress_percent": 1.0
            },
            {
                "name": "electricity",
                "label": "electricity",
                "progress": 0,
                "research_points": 1000,
                "description": "unlocks electrical power generation and basic electrical devices.",
                "is_finished": false,
                "can_start_now": true,
                "player_has_any_appropriate_research_bench": true,
                "required_analyzed_thing_count": 0,
                "analyzed_things_completed": 0,
                "tech_level": "industrial",
                "prerequisites": ["basic_research"],
                "hidden_prerequisites": [],
                "required_by_this": ["microelectronics"],
                "progress_percent": 0.0
            }
        ]
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-12T10:00:00.0000000Z"
}

GET


/api/v1/research/project

¶

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

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/research/project?name=Microelectronics'

Response:

{
    "success": true,
    "data": {
        "name": "Microelectronics",
        "label": "Microelectronics",
        "progress": 500,
        "research_points": 3000,
        "description": "build advanced components and electronics.",
        "is_finished": false,
        "can_start_now": true,
        "player_has_any_appropriate_research_bench": true,
        "required_analyzed_thing_count": 0,
        "analyzed_things_completed": 0,
        "tech_level": "Industrial",
        "prerequisites": ["Electricity"],
        "hidden_prerequisites": [],
        "required_by_this": ["Fabrication", "AdvancedMachining"],
        "progress_percent": 0.16666667
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-12t10:00:00.0000000z"
}

GET


/api/v1/research/summary

¶

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

Example:

curl --request GET \
--url 'http://localhost:8765/api/v1/research/summary'

Response:

{
    "success": true,
    "data": {
        "finished_projects_count": 3,
        "total_projects_count": 50,
        "available_projects_count": 15,
        "by_tech_level": {
            "neolithic": {
                "finished": 1,
                "total": 5,
                "percent_complete": 20.0,
                "projects": ["BasicResearch"]
            },
            "industrial": {
                "finished": 2,
                "total": 10,
                "percent_complete": 20.0,
                "projects": ["Electricity", "Stonecutting"]
            }
        },
        "by_tab": {
            "basic": {
                "finished": 2,
                "total": 10,
                "percent_complete": 20.0,
                "projects": ["BasicResearch", "Stonecutting"]
            },
            "power": {
                "finished": 1,
                "total": 5,
                "percent_complete": 20.0,
                "projects": ["electricity"]
            }
        }
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2025-12-12T10:00:00.0000000Z"
}

POST


/api/v1/research/target

¶

Устанавливает активный исследовательский проект колонии по его defName. Это немедленно перенаправляет фокус исследований колонии.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/research/target?name=Electricity&force=false'

Response:

{
    "success": true,
    "data": {
        "finished_projects_count": 3,
        "total_projects_count": 50,
        "available_projects_count": 15,
        "by_tech_level": {
            "neolithic": {
                "finished": 1,
                "total": 5,
                "percent_complete": 20.0,
                "projects": ["BasicResearch"]
            },
            "industrial": {
                "finished": 2,
                "total": 10,
                "percent_complete": 20.0,
                "projects": ["Electricity", "Stonecutting"]
            }
        },
        "by_tab": {
            "basic": {
                "finished": 2,
                "total": 10,
                "percent_complete": 20.0,
                "projects": ["BasicResearch", "Stonecutting"]
            },
            "power": {
                "finished": 1,
                "total": 5,
                "percent_complete": 20.0,
                "projects": ["electricity"]
            }
        }
    },
    "errors": [],
    "warnings": [],
    "timestamp": "2026-03-28T16:10:00.0000000Z"
}

POST


/api/v1/research/stop

¶

Останавливает текущий активный исследовательский проект колонии. Это снимает фокус исследования и возвращает состояние проекта, который был остановлен. Возвращает ошибку, если в данный момент нет активных исследований.

Example:

curl --request POST \
--url 'http://localhost:8765/api/v1/research/stop'

Response:

{
  "success": true,
  "errors": [],
  "warnings": [],
  "timestamp": "2026-02-18T13:22:46.312391Z"
}

⚙️ Game State & Mechanics API¶

Игра¶

GET /api/v1/game/state ¶

POST /api/v1/game/speed ¶

GET /api/v1/game/settings/run-in-background ¶

POST /api/v1/game/settings/toggle/run-in-background ¶

GET /api/v1/version ¶

GET /api/v1/mods/list ¶

GET /api/v1/mods/info ¶

GET /api/v1/mods/preview ¶

POST /api/v1/mods/configure ¶

POST /api/v1/select ¶

POST /api/v1/deselect ¶

POST /api/v1/open-tab ¶

GET /api/v1/def/all ¶

POST /api/v1/game/select-area ¶

POST /api/v1/game/send/letter ¶

POST /api/v1/game/save ¶

POST /api/v1/game/load ¶

POST /api/v1/game/start/devquick ¶

POST /api/v1/game/start ¶

GET /api/v1/game/settings ¶

POST /api/v1/game/main-menu ¶

POST /api/v1/game/quit ¶

Игровые события¶

GET /api/v1/quests ¶

GET /api/v1/incidents ¶

GET /api/v1/lords ¶

GET /api/v1/incidents/top ¶

GET /api/v1/incident/chance ¶

POST /api/v1/incident/trigger ¶

Фракции¶

GET /api/v1/factions ¶

GET /api/v1/faction/relations ¶

GET /api/v1/faction/player ¶

GET /api/v1/faction ¶

GET /api/v1/faction/relation-with ¶

GET /api/v1/faction/def ¶

POST /api/v1/faction/change/goodwill ¶

GET /api/v1/faction/icon ¶

POST /api/v1/faction/goodwill ¶

Исследования¶

GET /api/v1/research/progress ¶

GET /api/v1/research/finished ¶

GET /api/v1/research/tree ¶

GET /api/v1/research/project ¶

GET /api/v1/research/summary ¶

POST /api/v1/research/target ¶

POST /api/v1/research/stop ¶

GET

`/api/v1/game/state` ¶

POST

`/api/v1/game/speed` ¶

GET

`/api/v1/game/settings/run-in-background` ¶

POST

`/api/v1/game/settings/toggle/run-in-background` ¶

GET

`/api/v1/version` ¶

GET

`/api/v1/mods/list` ¶

GET

`/api/v1/mods/info` ¶

GET

`/api/v1/mods/preview` ¶

POST

`/api/v1/mods/configure` ¶

POST

`/api/v1/select` ¶

POST

`/api/v1/deselect` ¶

POST

`/api/v1/open-tab` ¶

GET

`/api/v1/def/all` ¶

POST

`/api/v1/game/select-area` ¶

POST

`/api/v1/game/send/letter` ¶

POST

`/api/v1/game/save` ¶

POST

`/api/v1/game/load` ¶

POST

`/api/v1/game/start/devquick` ¶

POST

`/api/v1/game/start` ¶

GET

`/api/v1/game/settings` ¶

POST

`/api/v1/game/main-menu` ¶

POST

`/api/v1/game/quit` ¶

GET

`/api/v1/quests` ¶

GET

`/api/v1/incidents` ¶

GET

`/api/v1/lords` ¶

GET

`/api/v1/incidents/top` ¶

GET

`/api/v1/incident/chance` ¶

POST

`/api/v1/incident/trigger` ¶

GET

`/api/v1/factions` ¶

GET

`/api/v1/faction/relations` ¶

GET

`/api/v1/faction/player` ¶

GET

`/api/v1/faction` ¶

GET

`/api/v1/faction/relation-with` ¶

GET

`/api/v1/faction/def` ¶

POST

`/api/v1/faction/change/goodwill` ¶

GET

`/api/v1/faction/icon` ¶

POST

`/api/v1/faction/goodwill` ¶

GET

`/api/v1/research/progress` ¶

GET

`/api/v1/research/finished` ¶

GET

`/api/v1/research/tree` ¶

GET

`/api/v1/research/project` ¶

GET

`/api/v1/research/summary` ¶

POST

`/api/v1/research/target` ¶

POST

`/api/v1/research/stop` ¶