Введение

Папки SpaceEngine

В SpaceEngine есть две основные папки с файлами данных, которые находятся в корневом каталоге (каталоге установки): data и addons. Они эквивалентны во многих аспектах. Первая содержит стандартные файлы SpaceEngine, которые не рекомендуется изменять. Вторая зеркально повторяет внутреннюю структуру первой, и используется для пользовательских модов и аддонов. Она также имеет более высокий приоритет при поиске файлов при запуске. Это значит, что если у вас есть какой-то файл в папке addons с таким же путём и именем, как какой-то файл в папке data, SpaceEngine загрузит файл из папки addons. Это полезно для создания модов, которые изменяют некоторые из системных файлов, таких как шейдеры, без фактического изменения самих системных файлов.

Внутри папка data содержит следующие стандартные подпапки: catalogs, ephemerides, locale, models, music, scripts, shaders, sounds, textures. Слово «стандартные» означает, что SpaceEngine ожидает найти конкретные файлы данных в этих вложенных папках, например, файлы саундтрека должны быть в data/music/, а каталоги звёзд - в data/catalogs/stars/ (некоторые из стандартных папок содержат свои собственные стандартные папки следующего уровня).

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

В папке addons также допустимо использовать дополнительные вложенные папки, для лучшей организации аддонов. Эти дополнительные папки могут иметь любое имя (которое, очевидно, не может совпадать с именем стандартной папки), как правило, отражающее имя аддона или франшизы, например addons/StarWars/. Внутри дополнительная папка может содержать стандартные папки с файлами данных: catalogs, models, textures и т.д., или pak-файлы (см. ниже), или же она может содержать дополнительную вложенную папку следующего уровня, например addons/StarWars/EmpireShips/. SpaceEngine допускает неограниченное количество вложенных папок (ограниченно только операционной системой - как правило, длина пути не должна превышать 256 символов).

pak-файлы

Pak-файлы - это zip-архивы, использующиеся для лучшей организации и распространения игрового контента. Например, большой аддон с тысячами файлов может быть заархивирован в один pak-файл и распространяться в таком виде - это удобно для пользователя. Также, при создании pak-файла может использоваться сжатие, что полезно для экономии дискового пространства и трафика.

Pak-файлы включают в себя файлы и папки с той же структурой, как на диске, начиная с корневого уровня data и addons (или addons/YourCustomFolder/). Это значит, что самая верхняя папка, которая может быть заархивирована в pak-файл - это одна из стандартных папок: catalogs, models, textures и т.д. SpaceEngine считывает содержимое всех pak-файлов при запуске и использует их для организации виртуальной файловой системы с приоритетом даты модификации.

1) Формат pak-файла

Как уже говорилось, pak-файлы - это zip-архивы (т.е. .zip файлы с расширением, изменённым на .pak). Вы можете связать тип файла .pak с WinRAR или 7zip или любой другой программой-архиватором, поддерживающей zip, и открывать pak-файлы в ней. Создавать pak-файлы просто: выберите нужные файлы и папки и запакуйте их в zip-архив, а потом переименуйте его в .pak.

2) Виртуальный путь

Можно представлять pak-файл как контейнер для файлов/папок. Внутренняя структура папок внутри pak-файла является продолжением структуры папок SE, они "прозрачны" для SE. Это значит, что pak-файл выглядят для SE так, как если бы всё его содержимое было извлечено на диск в том месте, где этот pak-файл находится. Мы будем называть это виртуальный путь. Далее в этой статье будет применяться следующая цветовая маркировка: пути к файлам и папкам на диске (не запакованным) окрашены в зелёный цвет, а пути внутри pak-файла - в оранжевый цвет. Например, эти три виртуальные пути равнозначны (помните, что папка StarWars необязательна):
addons/StarWars/StarWarsPlanets.pak/catalogs/planets/Coruscant.sc (упакованный в pak-файл)
addons/StarWars/catalogs/planets/Coruscant.sc (распакованный на диск)
addons/catalogs/planets/Coruscant.sc (распакованный на диск, без опциональной папки StarWars)

3) Приоритет по дате изменения

Если есть два или более файлов с одинаковым виртуальным путём, SE будет загружать самый новый из них. SE сравнивает дату/время модификации файлов на диске, или дату/время модификации всего pak-файла. Например, рассмотрим 3 файла SolarSys.sc в разных местах, но с одинаковым виртуальным путём:
data/catalogs/Catalogs0980.pak/planets/SolarSys.sc (в стандартном pak-файле SE, дата модификации pak-файла 06.08.2016)
data/catalogs/planets/SolarSys.sc (извлечён на диск, дата модификации файла файла 01.09.2016)
data/catalogs/SolarSysUpdate001.pak/planets/SolarSys.sc (в другом pak-файле, дата модификации которого 05.09.2016)
В этом примере SpaceEngine загрузит последний файл, так как он имеет самую "свежую" дату. Это полезно для создания обновлений. Пусть теперь кто-то добавил аддон с таким файлом:
addons/SolarSystemMod.pak/catalogs/planets/SolarSys.sc (дата модификации pak-файла 15.08.2016)
В этом случае SpaceEngine загрузит файл из этого аддона, несмотря на то, что он старше pak-файла обновления из предыдущего примера. Это происходит потому, что файлы в папке addons имеют приоритет над файлами в папке data. Это сделано для того, чтобы сохранить работоспособность аддонов после установки обновления SpaceEngine. Но внутри папки addons действует то же правило приоритета по дате модификации файла/пака.

4) Извлечение файлов

Вы можете извлечь любой файл из pak-архива, открыв его как zip-архив. При извлечении файла, необходимо создать все подпапки, в которой он находится внутри pak-файла, так, чтобы извлечённый файл имел тот же виртуальный путь, как и упакованный (как при использовании команды "Извлечь здесь" в контекстном меню Проводника). Например, если вы хотите, извлечь файл SolarSys.sc из Catalogs0980.pak, необходимо создать папку data/catalogs/planets/ и извлечь этот файл в него, так чтобы у него был такой путь:
data/catalogs/planets/SolarSys.sc
После этого SpaceEngine будет загружать этот извлечённый файл, так как он будет иметь более позднюю дату. Теперь можно радактировать его.

5) Создание pak-файлов

Например, вы делаете аддон с планетными системами, состоящий из следующих файлов:
addons/StarWars/catalogs/stars/StarWarsSystems.sc
addons/StarWars/catalogs/planets/Coruscant.sc
addons/StarWars/catalogs/planets/Tatooine.sc

Когда вы закончите его создание и тестирование, и будете готовы к релизу, перейдите в папку addons/StarWars/, выберите папку catalogs и упакуйте её в zip-архив, затем переименуйте его StarWarsPlanets-v001.pak. Имя файла не имеет значения, но оно должно отражать содержимое файла; также хорошей идеей будет указание номера версии/ревизии. После этого можно удалить папку catalogs со всем содержимым (или переместить её в какое-то резервное место) и оставить только вновь созданный pak-файл. Если вы сделали всё правильно, ваш аддон должен работать в SE, как и раньше. Файлы данных должны иметь такой виртуальный путь:
addons/StarWars/StarWarsPlanets.pak/catalogs/stars/StarWarsSystems.sc
addons/StarWars/StarWarsPlanets.pak/catalogs/planets/Coruscant.sc
addons/StarWars/StarWarsPlanets.pak/catalogs/planets/Tatooine.sc
Теперь можно выложить файл StarWarsPlanets-v001.pak на всеобщий доступ. Обратите внимание, что он будет работать, будучи помещённым в любую вложенную папку в папке addons (естественно, кроме стандартных вложенных папок):
addons/StarWarsPlanets-v001.pak
addons/StarWars/StarWarsPlanets-v001.pak
addons/blabla/ololo/123/StarWarsPlanets-v001.pak
Можно запаковать любой набор файлов данных в один pak-файл. Например, вы можете создать полный аддон франшизы «Звёздные войны», который включает в себя все планетные системы, галактику и модель галактики, и все модели кораблей. Правда, существуют некоторые ограничения, описанные ниже.

6) Ограничения

1) pak-файлы не могут находиться в корневой папке SpaceEngine. Такое не будет работать:
SpaceEngine/StarWars.pak/data/catalogs/planets/Coruscant.sc
2) pak-файл не может содержать дополнительные вложенные папки, допустимо использование только стандартных папок. Такое не будет работать:
SpaceEngine/addons/StarWars.pak/StarWars/StarWarsPlanets/catalogs/planets/Coruscant.sc
3) pak-файл должен иметь размер не более 4 гигабайт. Если вы не вписываетесь в этот размер, разделите ваш аддон на несколько более мелких pak-файлов.
4) Музыка и звуковые файлы в формате .ogg не могут быть заархивированы в pak-файл.

7) Степень сжатия

Zip-архивы могут быть созданы с использованием сжатия или без сжатия. SpaceEngine поддерживает только "Deflate" метод сжатия. Некоторые типы файлов хорошо сжимаются (текстовые файлы, такие как скрипты и каталоги), некоторые - средне (двоичные файлы, такие как модели кораблей .sm, текстуры в формате .dds и несжатом .tga), некоторые почти не сжимаются (текстуры в формате .jpg, .png, .tif). Рекомендуется упаковывать большой массив текстур (например, аддон с текстурами планеты) в архив без сжатия, так как он имеет большую производительность при извлечении/загрузке текстур в SE. Более высокая производительность всегда лучше, чем экономия нескольких мегабайт дискового пространства. Вы можете поэкспериментировать с целью найти лучшую степень сжатия для вашего аддона. Например, можно сохранить текстуры в pak-файл без сжатия, а скрипты и модели в другой pak-файл со сжатием.

8) Никогда не изменяйте стандартные pak-файлы

Так же, как и во всех других играх, изменение стандартных ресурсов игры - плохая идея. В будущем, клиент игры будет проверять свои стандартные файлы на предмет изменения, и выгонять вас с сервера, если таковое будет обнаружено. Так что запомните простые правила:
1) Если вы хотите что-то добавить, создайте свой собственный pak-файл (или просто храните файлы в папках, не упаковывая их).
2) Если вы хотите изменить что-то, извлеките файл из стандартного pak-файла, и изменяйте извлечённый файл.

Скрипты SpaceEngine

SpaceEngine имеет специальный скриптовый язык для описания астрономических объектов, кораблей, моделей и файлов конфигурации, а также для написания сценариев. Скрипты хранятся в файлах с расширениями *.sc, *.sss, *.cfg, *.se. Это обычные текстовые файлы, которые можно редактировать с помощью блокнота (или программы Notepad++, которую мы рекомендуем скачать и установить). Давайте посмотрим на какой-нибудь из стандартных sc-файлов SpaceEngine. Например, вот описание Сатурна, находящееся в файле data/catalogs/Catalogs0980.pak/planets/SolarSys.sc:

Code

Planet   "Saturn"
{

ParentBody     "Sol"
Class          "GasGiant"    Mass            95.162
Radius          60268
Oblateness      0.09796RotationPeriod  10.65622
RotationOffset  358.922
Obliquity       28.049
EqAscendNode    169.53Color         ( 1.000 1.000 0.850 )
Albedo          0.342
AlbedoBond      0.342
AlbedoGeom      0.47
Brightness      1.8Surface
{

// Surface map author: Bjorn Jonsson
DiffMap        "Saturn/Surface-BJ"
DiffTileSize    256
DiffTileBorder  0
DayAmbient      0
NoClouds     true

}
Atmosphere
{

Height   250  // km
Model   "Earth"
Bright   5.0
Opacity  0.2
SkyLight 0.002

Composition // values in percent
{

H2   96.3
He   3.25
CH4  0.45
NH3  0.0125
C2H6 0.0007

}

}

Aurora
{

Height       1000   // km
TopColor    (1.5 0.0 0.8)
BottomColor (1.0 0.1 0.0)
NorthLat     90    // degrees
NorthLon     0     // degrees
NorthRadius  15000 // km
NorthWidth   5000  // km
NorthRings   3     // number of rings
NorthBright  1.0
SouthLat    -90    // degrees
SouthLon     0     // degrees
SouthRadius  16000 // km
SouthWidth   5000  // km
SouthRings   3     // number of rings
SouthBright  1.0

}

Rings
{

// Rings texture author: Vladimir Romanyuk "SpaceEngineer"
Texture        "Saturn-rings.*"
InnerRadius     60284
OuterRadius     356993
FrontBright     1.0
BackBright      5.0
Brightness      1.5

}

Orbit
{

RefPlane       "Ecliptic"
Period          29.4577
SemiMajorAxis   9.5371
Eccentricity    0.0542
Inclination     2.4845
AscendingNode   113.715
LongOfPericen   92.432
MeanLongitude   49.944

}

}

Скрипт начинается с ключевого слова Planet и следующей за ней текстовой строкой "Saturn". После этого идут строки с параметрами, заключёнными в фигурные скобки. Такая конструкция Planet "Saturn" {...} называется тег, и играет важную роль в скриптах SE. Теги делят скрипт на логические секции, они могут также включать в себя другие теги (например, Surface {...}).

Теги могут быть именованными, например, тег Planet, или неименованными, например Surface. Именованный тег может иметь несколько имён (альтернативные имена), разделённые косой чертой '/'. Например: Star "ALF Cen/Toliman/Rigel Kentaurus/Gliese 559". Все эти имена идентифицируют один и тот же объект в SpaceEngine, они могут в равной степени использоваться как для поиска объекта в программе, так и в качестве ссылки на объект из других скриптов (например, вы должны указывать имя звезды в параметре ParentBody скрипта планеты; для этого можно использовать одно из несколько альтернативных имён звезды).

Греческие буквы в имени объекта вводятся в виде аббревиатур: ALF, BET и т.д. Полный список аббревиатур:

ALFα(aльфа)
BETβ(бета)
GAMγ(гамма)
DELδ(дельта)
EPSε(эпсилон)
ZETζ(дзета)
ETAη(эта)
TETθ(тета)
IOTι(йота)
KAPκ(каппа)
LAMλ(лямбда)
MUμ(мю)
NUν(ню)
KSIξ(кси)
OMIο(омикрон)
PIπ(пи)
RHOρ(ро)
SIGσ(сигма)
TAUτ(тау)
UPSυ(ипсилон)
PHIφ(фи)
CHIχ(хи)
PSIψ(пси)
OMEω(омега)

Параметр - это строка с именем параметра (ключевое слово) слева и значением параметра справа. Имя и значение должны быть разделены пробелами или через табуляциями. Допускается только один параметр в каждой строке скрипта. Параметры могут быть следующих типов:

текстовая строка: Class "GasGiant"
число: Mass 95.162
вектор: Color ( 1.000 1.000 0.850 ) или Color ( 1.000, 1.000, 0.850 )
число в формате 'град мин сек' или 'час мин сек': Dec 18 32 16.23
логический тип: NoClouds true или NoClouds 1

Поддерживаются комментарии в формате языка C/C++:
// однострочный комментарий
/* инлайн-комментарий */
Первый - это однострочный комментарий. Весь текст после символов // до конца строки считается комментарием и игнорируется. Второй - это инлайн или многострочный комментарий. Весь текст между символами /* и */ считается комментарием и игнорируется. Переводы строки также допускаются в этом типе комментария:
/* это пример
многострочного
комментария */

Каталоги астрономических объектов

SpaceEngine хранит информацию обо всех заданных вручную ("каталожных") объектах в скрипт-файлах (с расширением *.sc) или в csv-файлах (*.csv), расположенных в виртуальной папке */catalogs/. Оба формата файлов - простые текстовые документы, так что вы можете редактировать их с помощью блокнота. Файлы csv также можно редактировать с помощью специализированного программного обеспечения (например Microsoft Excel, с некоторыми побочными эффектами). Каталог */catalogs/ содержит подкаталоги galaxies/, clusters/, nebulae/, stars/ и planets/, для каждого типа объекта.

Большинство звёзд в стандартной установке SpaceEngine хранятся в csv-файле data/catalogs/Catalogs0980.pak/stars/HIPPARCOS.csv, а галактик - в data/catalogs/Catalogs0980.pak/galaxies/NGC-IC.csv. Это звёздный каталог HIPPARCOS, содержащий около 110 000 звёзд, и каталог галактик NGC/IC - около 10 000 галактик. Другие объекты - галактики звёзды с дополнительными параметрами, двойные звёзды, чёрные дыры, звёздные скопления и туманности, объекты Солнечной системы, экзопланеты и их родительские звёзды - хранятся в нескольких sc-файлах в том же системном pak-файле. Эти системные файлы не должны редактироваться или изменяться каким-либо образом. Если вы хотите обновить звезду, удалить или добавить новую, создайте свой собственный sc или csv файл в папке addons/catalogs/stars/. SpaceEngine поддерживает функции для изменения и удаления звёзд или любых других объектов из стандартных каталогов, а так же для добавления новых. После завершения работы над каталогами, вы можете запаковать их в pak-файл и распространять аддон в таком виде.

Формат csv для каталогов предназначен для создания больших каталогов с однообразными данными. Он более компактный и загружается быстрее, чем sc, но допускает ограниченное количество типов данных, которые могут быть указаны в нем. Это просто таблица со значениями, разделёнными запятыми. Формат sc предназначен для описания объектов с любыми возможными типами данных, которые только могут быть использованы в SpaceEngine. Это текстовый скрипт, использующий "теги" для описания объекта (галактики, звезды, планеты и т.д.) и различных его параметров.

Добавление, обновление и удаление объектов

Если вы опишете какой-то новый объект, используя sc-файл SpaceEngine, он будет добавлен в игру. Под "новым объектом" подразумевается объект, который не существовал ранее в SE (не был описан ни в одном из каталогов). Точнее, объект того же типа (например, звезда) и с тем же именем не существовал ранее в SE. Если объект того же типа и с таким же именем уже существует в SE, произойдёт его обновление или объединение с данными, которые вы предоставили в вашем новом скрипте. Порядок обновления (какие именно данные имеют приоритет) определяется датой изменения sc-файла или pak-файл, в который этот sc-файл запакован. Более новый файл имеет больший приоритет, поэтому некоторые данные из скрипта объекта в предыдущем файле будут заменены новыми данным. Если какие-то данные отсутствуют в предыдущем скрипте (например, масса планеты), но есть в новом, будут использоваться данные из нового скрипта.

Планетарные объекты (планеты, луны, астероиды, кометы и звёзды в кратных звёздных системах) идентифицируются немного сложнее. SpaceEngine позволяет задавать множество планетарных объектов с одним и тем же именем, но с различающимся родительским объектом (указанным в параметре ParentBody). Например, Солнечная система имеет два объекта с именем "Pandora": спутник Сатурна и астероид. Они имеют разные родительские объекты - соответственно Сатурн и Солнце, так что это - разные объекты в SE.

В процессе поиска одинаковых объектов, SpaceEngine сканирует все альтернативные имена, представленные в скрипте. Например, вы можете обновить старую звезду Star "ALF Cen/Toliman/Rigel Kentaurus/Gliese 559", описав новую звезду в тегом Star "Toliman/Bungula". SpaceEngine обнаружит, что это один и тот же объект, т.к. найдёт совпадающее имя "Toliman". Произойдёт обновление старой звезды новыми данными, указанными в новом скрипте, в том числе обновится имя звезды: SE добавит новое имя "Bungula" в список альтернативных имён, так что он станет "ALF Cen/Toliman/Bungula/Rigel Kentaurus/Gliese 559". Для планетарного объекта, как было отмечено, вы должны указать также родительский объект. SpaceEngine объединит планетарные объекты, только если совпадают имена самих объектов и имена их родителей (можно использовать любое из альтернативных имён родителя).

Можно отменить некоторые данные из предыдущего скрипта. Например, параметр NoClouds true отменяет теги Clouds { } в старых скриптах. Наоборот, теги Clouds { } в новом скрипте отменяет NoClouds true в старом.

Можно также изменить тип объекта, переопределив его другим тегом. Например, если в каком-то старом скрипте определена планета "Kek" таким образом: Planet "Kek", а вы создали новый скрипт, определив в нём тег Moon "Kek", то планета в игре станет луной. Изменение типа возможно только в пределах того множества типов, который поддерживается в данном каталоге. Это значит, что вы не можете описать галактику с именем "Saturn" в каталоге планет, используя тег Galaxy "Saturn". Он будет проигнорирован SE, так как тег Galaxy не допускается в каталоге планет. Вот список типов объектов (тегов), которые разрешены в соответствующих каталогах:

Каталог планет */catalogs/planets/*.sc: Star, Planet, Moon, DwarfPlanet, DwarfMoon, Asteroid, Comet, Barycenter
Каталог звёзд */catalogs/stars/*.sc: Star, StarBarycenter
Каталог галактик */catalogs/galaxies/*.sc: Galaxy, Quasar
Каталог звёздных скоплений */catalogs/clusters/*.sc: Cluster
Каталог туманностей */catalogs/nebuale/*.sc: Nebula

Можно удалить (точнее, отключить) какой-либо объект из старых каталогов. Используйте параметр Remove с именем того объекта, который вы хотите удалить. Например, Remove "Toliman". Он должен указываться вне тегов. Можно использовать любое из альтернативных имён объекта. Звёздный каталог также поддерживает параметр RemoveStar, который работает аналогично (для обратной совместимости). В каталоге планет вы должны использовать более сложную конструкцию: Remove "Saturn" { ParentBody "Sol" }. Поскольку, как уже говорилось, SpaceEngine идентифицирует планетарные объекты по их собственному имени и имени их родителя.

Удаление старых объектов может быть использовано для обновления стандартных каталогов SE. Например, звёздные каталоги всё ещё содержат много двойных звёзд, описанных как две одиночные звезды. Можно использовать параметр Remove в каталоге звёзд, чтобы удалить их, и в нём же описать барицентр системы. Затем в каталоге планет описать две звезды-компонента двойной, с соответствующими орбитами, и тем барицентром в качестве родителя. Подробнее см. Создание звёзд.

Примечание: параметр Remove действует на все файлы каталогов, независимо от их даты модификации. Так что применив его один раз, вы не сможете более создать объект того же типа с тем же именем. Это баг в текущей версии (0.9.8.0).

Проверка каталогов на ошибки

SpaceEngine может писать предупреждения и сообщения об ошибках в лог-файл system/se.log при загрузке каталогов. Есть два способа включить ведение журнала: глобальный и в каждом файле каталога отдельно. Глобальный уровень протоколирования управляется параметрами CatalogLogLevel (для sc-файлов) и CsvLogLevel (для csv-файлов) в теге Log файла конфигурации config/main-user.cfg. Возможные значения уровня:

0 - ничего не писать в лог
1 - писать ошибки и предупреждения, используя меньший из уровней в main-user.cfg и в sc-файле, если он определён там
2 - писать всё, используя меньший из уровней в main-user.cfg и в sc-файле, если он определён там
3 - писать ошибки и предупреждения, игнорируя уровень в sc-файле
4 - писать всё, игнорируя уровень в sc-файле

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

Каждый sc-файл каталогов может иметь собственные настройки уровня протоколирования, заданный параметром LogLevel, указанный где-то в глобальном пространстве (т.е. вне тегов Star, StarBarycenter и пр.). Возможные значения:

0 - ничего не писать в лог
1 - писать ошибки и предупреждения
2 - писать всё

Пока вы работаете над каталогами, рекомендуется указать LogLevel 2 в ваших sc-файлах и CatalogLogLevel 2 в main-user.cfg. Таким образом вы будете иметь всю информацию о работе звёздного калькулятора в лог-файле (см. Создание звёзд). Если вам нужно видеть только возможные ошибки, укажите LogLevel 1 в sc-файле. Если в финальной версии ваших каталогов всё ещё выводятся какие-то ошибки или предупреждения (например, когда отсутствуют данные RA/Dec, и звёздный калькулятор генерирует их процедурно), рекомендуется указать в них LogLevel 0, так что лог-файлы других пользователей будут свободны от ошибок, связанных с вашими каталогами.