kOS: справочник библиотеки kerbal.ru

Точный справочник по библиотеке, которую установщик кладёт в Ships/Script/. Если kOS: библиотека модулей объясняет почему модули устроены так, то здесь — что именно вызывать: сигнатуры, возвращаемые значения и побочные эффекты.

Написано так, чтобы ответ находился за один взгляд — и человеком, и ИИ-агентом, которому дали доступ к терминалу.

Как это загружается

Модули подключаются через RUNONCEPATH, зависимости тянутся сами:

RUNONCEPATH("0:/lib/mission.ks").   // подтянет все девять модулей

Префикс в имени = модуль. u_ — util, o_ — orbit, a_ — ascent, s_ — stage, c_ — ctrl, d_ — deploy, t_ — telem, h_ — hud, m_ — mission, r_ — rendezvous, x_ — transfer, l_ — land, e_ — events, ds_ — deepspace, q_ — audit. У науки исторически sci. Это не украшение: в kOS все имена глобальны, префикс — единственная защита от столкновений.

mission.ks — миссия целиком

Ключи spec:

Перепутанные местами ap и pe функция меняет молча — на результат это не влияет.

util.ks — углы, азимут, окно пуска

Две константы подобраны по нашей телеметрии и для другого сейва их надо перемерить:

• U_AZ_BIAS (−0,45°) — поправка азимута. Расчёт давал 80,80°, полёт дал наклонение 8,02° вместо 8,50°.
• U_LAN_C (91,80°) — сдвиг в модели LAN = долгота старта + поворот планеты + C. Каждая миссия печатает в конце строку калибровка узла: lon=… UT=… LAN=… — по трём таким числам константа пересчитывается.

u_limitTo — ядро защиты от заваливания: команда рулю никогда не уходит от набегающего потока дальше допустимого угла атаки. Без неё ракета переворачивается на 20 км, мы это проходили.

orbit.ks — узлы манёвра

Функции с o_node… только создают узел и возвращают его. Исполняет o_burn, он же добавляет узел в план и снимает после.

Что o_burn делает с кораблём: выключает SAS (одновременно с kOS рулить нельзя), даёт импульс РСУ на разворот, ждёт наведения с точностью 2°, перематывает до половины времени прожига, жжёт с затуханием тяги к концу, стейджит при выгорании, затем снимает узел, включает SAS и ждёт полсекунды. onTick вызывается каждый проход — туда передают m_tick@ для логов.

Почему ADD внутри o_burn, а не в фабриках. У неприкреплённого узла нельзя спросить :DELTAV — kOS отвечает «Must attach node first» прямо в полёте. Владелец один, место одно.

ascent.ks — подъём

Настройки cfg: park (апоцентр опорной), az (азимут), vVert (до какой скорости идём строго вверх, 60 м/с), hDense (граница плотного воздуха, 25 км), aoaLo/aoaHi (допуск угла атаки: 5° внизу, 20° выше), hTwr/twrMax (потолок перегрузки 2,3 до 22 км), qMax (потолок напора 0,32 атм), aoaAlarm, onTick.

a_run вешает аварийный триггер: падение со скоростью снижения ниже −10 м/с в диапазоне 3–60 км глушит тягу и возвращает FALSE.

Расписание тангажа уплощалось по итогам реальных пусков: слишком крутой подъём приводит аппарат к апоцентру почти без горизонтальной скорости, и скругление стоит впятеро дороже. Числа в a_pitchSchedule — результат этих правок, а не теория.

transfer.ks — перелёт к другому телу

У CelestialBody в kOS те же суффиксы ORBIT/POSITION/VELOCITY, что у Vessel — поэтому геометрия перелёта к Муну использует те же функции r_nodeMatchPlanes/r_nodeTransfer из rendezvous.ks, что и рандеву с аппаратом. Новое здесь — прицельный перицентр у чужой сферы влияния и захват с гиперболы.

x_go наклонение к телу не подгоняет — закладывай его на пуске у родителя, как в Рандеву и стыковка: смена плоскости уже у цели дорога.

land.ks — посадка на тело без атмосферы

Только для тел без атмосферы: с воздухом сопротивление меняет картину, там нужна связка «парашют → l_descend», а не она одна.

l_facingBody/l_waitFacing дают полушарие, не точку: деорбит стартует над нужной стороной, снос при спуске небольшой относительно размера тела, но не нулевой — точное прицеливание в координаты не решено (см. kos/README.md, список открытого). Вызывать l_facingBody(refBody) имеет смысл только когда SHIP:BODY — не сам refBody: если тело совпадает, направление на него вырождается в нулевой вектор.

events.ks — событийная автоматика

Замена линии WAIT/IF на список «что и когда» — переживает варп и смену фокуса, потому что условия проверяются заново, а не хранятся в счётчиках.

deepspace.ks — дальний вылет одной спецификацией

Та же идея, что у m_orbit(spec): файл миссии содержит только параметры, решения — здесь.

Ключи spec: name, body (тело, по умолчанию MUN), parkAlt (низкая рабочая орбита захвата), mapAlt (картографическая полярная; 0 — не подниматься), landers (список меток декаплеров, пусто = отделяемых нагрузок нет), selfLand (TRUE — после развода нагрузок шина деорбитит и садится сама вместо подъёма в mapAlt), faceBody (-1 — без разницы; иначе тело, например KERBIN, — ждать витка над обращённым к нему полушарием перед посадкой), sci (снимать/передавать науку на рубежах и при каждом отделении), log.

landers — общее имя: под этой меткой может быть посадочный зонд, а может быть спутник созвездия, который остаётся на орбите — ds_release их не различает, разница только в том, что с ними происходит дальше. ds_run разносит их по равным долям витка, чтобы у них были разные наземные треки/фазы — точный выбор орбиты или биома под каждым остаётся за игроком, автомат этого не гарантирует. Сканеры SCANsat ds_run включает сразу после захвата (d_scan() из lib/deploy.ks) — чем раньше, тем больше витков успеют отснять.

audit.ks — чекеры по задаче и по телу

Проверка не пуском, а чтением деталей на столе: находит ли скрипт нужный прибор по названию, нужный модуль по классу, нужное число меток лендеров. Отдельно от libcheck.ks — тот ловит опечатки в коде, audit.ks смотрит, чем укомплектован конкретно ЭТОТ корабль.

Готовые списки под контракты (образцы, не полная база — паков контрактов десятки, добавляй свои по этому же шаблону):

И по телу — q_bodyDefaults() / q_bodyChecklist(spec) и два готовых пресета под Мун: q_bodyMun() (профиль «остаться картографом на орбите» — Δv ≥ 1150 м/с, заряд на теневую сторону ≥ 1400 ЭЧ либо РИТЭГ) и q_bodyMunTour() (профиль «развести спутники и сесть без обратного взлёта» — Δv ≥ 2700 м/с от опорной Кербина, заряд не проверяется: шина не сидит месяцами на орбите). spec["dv"] сверяется со стоковым счётчиком дельта-v игры (SHIP:DELTAV:VACUUM, KSP 1.11+) — если в настройках отключён Advanced Tweakables → Delta-V readout, вернётся 0, и это будет читаться как «не хватает», хотя на деле просто выключен показ.

План: телеметрия + чекеры + Δv-бюджет одной спецификацией

Тот же принцип, что у m_orbit/ds_run: логика в библиотеке, файл под конкретный корабль — только параметры.

Спецификацию под конкретный корабль в файл не сохраняют — собирают tasks/budget из готовых q_task*/q_body* и шлют q_plan(spec) прямо в терминал (через telnet — одной строкой, см. kOS по telnet: пульт снаружи игры). Ни двигателей, ни узлов манёвра — только чтение и арифметика, поэтому это безопасно гонять хоть каждый раз заново.

Чего чекер не видит — и не должен: хватит ли топлива именно этому лендеру, мягко ли он сядет, попадёт ли в нужный биом. Готовый прогон печатает список таких слепых зон отдельной строкой — не молчит о том, что не проверено.

sci.ks — наука

Настройки: SCI_MIN_VALUE (0.1) — порог, ниже которого замер не передаётся, а сбрасывается; SCI_ALLOW_ANIM — разрешить выдвижные приборы (включается только в вакууме); SCI_INCOMPATIBLE — модули с «наука» в названии класса, но НЕ с интерфейсом HASDATA/DEPLOY/DATA/TRANSMIT/DUMP (пример — SCANexperiment у SCANsat: своё событие «анализировать данные: тип», HASDATA на нём падает с «Suffix not found» — поймано на живом корабле через telnet); счётчики SCI_SENT, SCI_DUMPED.

Три правила, оплаченные потерянными антеннами, приборами и одним падением скрипта:

1. В атмосфере науку только собираем. Передача сама раскрывает складную антенну — в набегающем потоке её срывает.
2. Модули перебираются по индексу, а не через GETMODULE: тот возвращает только первый, а у мачты CA-AMA научных модулей два.
3. Не добавляй модуль в SCI_PASSIVE/SCI_ANIM по названию класса. «Science»/«Experiment» в имени не гарантирует совместимый интерфейс — проверяй суффиксы на реальном корабле (m:HASDATA и т.п.) до того, как включать в сбор, иначе sciSweep падает прямо во время полёта, а не на столе. sciAudit() для этого и существует.

Остальные модули

d_all ищет антенны по модулю ModuleDeployableAntenna и жмёт событие раскрытия — по-русски или по-английски, в зависимости от языка игры.

d_scan ищет модуль SCANsat (не путать с SCANexperiment на той же детали — это другой модуль, научный бонус-отчёт, несовместимый с sciSweep, см. SCI_INCOMPATIBLE в sci.ks) и жмёт любое его событие, начинающееся с «запустить сканирование» — у модуля их и есть ровно одно на тип сенсора (radar, multispectral…). У SCANsat-деталей нет отдельного «раскрыть»: сами они не складываются, включать нечего кроме сканирования. Названия событий сверены на живом корабле через telnet, не угаданы по каталогу.

Как проверить, не запуская

На стартовом столе прогоняется весь набор без включения двигателей:

RUNPATH("0:/check/libcheck.ks").

Это ловит опечатки и занятые встроенные имена — то, что иначе выясняется на 20-й секунде полёта. Список запрещённых имён (R, V, ALT, TIME, NODE, STAGE…) — в kOS: отладка и лимиты.

Что происходит от команды до орбиты по шагам — Автоматизация запуска по шагам. Устройство и обоснование решений — kOS: библиотека модулей. Данные корабля — kOS: справочник по данным корабля.