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

Каждая функция из lib/*.ks — что принимает, что возвращает, что делает с кораблём. Плюс порядок загрузки, соглашения об именах и настройки, которые задаются перед вызовом.

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

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

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

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

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

Модуль	Зависит от	Отвечает за
`util.ks`	—	углы, векторы, азимут пуска, окно узла
`ctrl.ks`	—	РСУ и снятие управления
`stage.ks`	—	отделение ступеней
`deploy.ks`	—	раскрытие панелей и антенн
`telem.ks`	—	запись телеметрии в CSV
`hud.ks`	—	подписи и стрелки на экране
`sci.ks`	—	сбор и передача науки
`orbit.ks`	`ctrl`, `stage`	узлы манёвра и их исполнение
`ascent.ks`	`util`, `ctrl`, `stage`	подъём с поверхности
`mission.ks`	все	миссия целиком

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

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

Функция	Принимает	Возвращает
`m_defaults()`	—	лексикон настроек со значениями по умолчанию
`m_orbit(spec)`	лексикон	`TRUE`, если вышли на орбиту; `FALSE`, если подъём прерван
`m_report(spec)`	лексикон	печатает «заказано / получилось»
`m_tick()`	—	один проход: наука, HUD, строка телеметрии

Ключи spec:

Ключ	По умолчанию	Смысл
`name`	`"миссия"`	имя в логах и на HUD
`ap`	`100000`	целевой апоцентр, м
`pe`	`-1`	целевой перицентр, м; `-1` = круговая
`inc`	`0`	наклонение, °
`lan`	`-1`	долгота восходящего узла, °; `-1` = не ждать окна
`aop`	`-1`	аргумент перицентра, °; `-1` = не важен
`park`	`80000`	высота опорной орбиты, м
`log`	`"0:/mission.csv"`	куда писать телеметрию
`hud`	`TRUE`	рисовать ли подписи на экране

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

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

Функция	Принимает	Возвращает
`u_clamp(x, lo, hi)`	числа	`x`, зажатый в границы
`u_pitchOf(vec)`	вектор	тангаж над горизонтом, °
`u_vPitch()`	—	тангаж вектора скорости; на скорости < 15 м/с даёт 90
`u_aoa()`	—	угол атаки, °; на скорости < 15 м/с даёт 0
`u_velAzimuth()`	—	компасный курс скорости, ° (0 = север)
`u_launchAzimuth(inc, vOrb)`	наклонение, скорость на опорной (по умолчанию 2279)	азимут пуска, °
`u_limitTo(from, to, lim)`	два вектора и предел, °	`to`, повёрнутый к `from` не дальше `lim`
`u_bodyRot(ut)`	момент времени	поворот планеты, °
`u_lanIfLaunchNow()`	—	какой узел получится при пуске сейчас, °
`u_lanWait(targetLan)`	узел, °	сколько секунд ждать
`u_waitForLan(targetLan, tol)`	узел, допуск (по умолчанию 2°)	ждёт окна, с перемоткой
`u_argLat()`	—	аргумент широты: угол от восходящего узла до нас, °
`u_utAtArgLat(target)`	угол, °	абсолютный момент, когда мы там окажемся

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

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_mu()` / `o_br()`	—	гравитационный параметр / радиус тела
`o_vCirc(rad)`	радиус от центра, м	круговая скорость, м/с
`o_vAt(rad, sma)`	радиус, большая полуось	скорость по вис-виве, м/с
`o_nodeCircularize()`	—	узел: скруглить в апоцентре
`o_nodeRaiseOpposite(alt)`	высота, м	узел: поднять противоположную апсиду
`o_nodeRaisePeri(alt)`	высота, м	узел: поднять перицентр
`o_nodeRaiseApoAt(alt, ut)`	высота, момент	узел: поднять апоцентр в заданный момент
`o_burn(nd, onTick)`	узел, необязательная функция	исполняет: наводится, перематывает, жжёт, снимает

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

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

ascent.ks — подъём

Функция	Принимает	Возвращает
`a_defaults()`	—	лексикон настроек подъёма
`a_pitchSchedule(hgt)`	высота, м	нужный тангаж, °
`a_steer(cfg)`	настройки	направление для `LOCK STEERING`
`a_throttle(cfg)`	настройки	газ 0…1
`a_run(cfg)`	настройки	`TRUE` при успехе, `FALSE` при аварии

Настройки 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 — результат этих правок, а не теория.

sci.ks — наука

Функция	Принимает	Возвращает
`sciVacuum()`	—	`TRUE`, если выше атмосферы
`sciZone()`	—	текущая зона: `"старт"`, `"атмосфера низко"`, `"космос высоко"`…
`sciModules()`	—	список научных модулей на борту
`sciSweep(label, mayTransmit)`	подпись, можно ли передавать	снимает показания, при `TRUE` передаёт
`sciTick()`	—	сработает только при смене зоны
`sciRetry()`	—	добор: сколько передано; `0` = больше нечего

Настройки: SCI_MIN_VALUE (0.1) — порог, ниже которого замер не передаётся, а сбрасывается; SCI_ALLOW_ANIM — разрешить выдвижные приборы (включается только в вакууме); счётчики SCI_SENT, SCI_DUMPED.

Два правила, оплаченные потерянными антеннами и приборами:

В атмосфере науку только собираем. Передача сама раскрывает складную антенну — в набегающем потоке её срывает.
Модули перебираются по индексу, а не через GETMODULE: тот возвращает только первый, а у мачты CA-AMA научных модулей два.

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

Функция	Что делает
`s_liveEngines()`	сколько двигателей работает и не выгорело
`s_need()`	нужна ли отсечка: ступень есть, готова, живых двигателей нет
`s_tick()`	отделяет, если нужно; `TRUE` = отделили
`c_rcs(want)`	включает РСУ, если монотоплива больше резерва (`C_MONO_RESERVE`, 4)
`c_rcsPulse()`	включить РСУ на `C_RCS_HOLD` секунд (3)
`c_rcsTick()`	выключить, когда время помощи истекло
`c_release()`	снять всё управление: газ, курс, РСУ, включить SAS
`d_vacuum()`	`TRUE` выше атмосферы
`d_all()`	раскрыть панели и антенны; в атмосфере не делает ничего
`t_init(path, header)`	начать лог, записать заголовок
`t_line(csv)`	строка в лог, не чаще `T_EVERY` (0,5 с)
`t_elapsed()`	секунд с начала записи
`h_init()` / `h_off()`	включить/выключить экранные подписи
`h_tick(cmd)`	обновить стрелки и цифры
`h_say(text)`	подпись на экране

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

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

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

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

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

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