Як побудовано opys

Ця сторінка для тих, хто збирається змінювати сам opys. Вона дає вам карту: що за частини, які правила тримають їх нарізно і з чого почати читати для звичайних видів змін.

Повний запис, з причиною кожного рішення, це CLAUDE.md у репозиторії. Ця сторінка це коротка версія.

Загальна картина

                 час збирання                    │       час запуску
                                                 │
  конфігурація ──▶ плагіни ──▶ злиття ──▶ маніфест─┼──▶ рантайм ──▶ гра
            (@opys/minecraft,   (@opys/dev)      │   (@opys/runtime)
             @opys/java, …)                      │
                                                 │
                      └────────── @opys/core ────┴──────────┘
                            формат, спільний для обох

Посередині стіна. Бік збирання і рантайм ніколи не імпортують один одного. Вони зустрічаються лише через маніфест, формат якого живе в @opys/core. Файл, в якому він публікується, бандл, це @opys/bundle. Це дозволяє лаунчеру везти малий рантайм окремо, а також дозволило б комусь переписати рантайм іншою мовою.

Усередині Rust, зверху TypeScript

Майже вся поведінка написана на Rust, у crates/. Один нативний аддон показує кожен крейт JavaScript, кожен під власним простором імен, і кожен пакет npm у packages/ це тонка типізована обгортка над крейтом з тим самим ім'ям:

crates/opys-forge             логіка
crates/opys-napi/src/forge.rs його простір імен   ──▶ @opys/binding, as `forge`
packages/forge                обгортка            ──▶ @opys/forge

Пакет імпортує власний простір імен і жоден інший. Перевірка меж це тримає, тож крейти лишаються такими ж окремими, як коли кожен мав власний аддон.

Те, що лишається в TypeScript, це те, що має лише JavaScript: функції автора конфігурації (зворотний виклик to не може перетнути межу до Rust), об'єкти плагінів та інструмент командного рядка.

Коли щось поводиться неправильно, виправлення майже завжди в крейті, і його тест там само.

Правила, яких ми дотримуємося

1. Формат це контракт. Зміна типу в opys-core змінює те, що читає кожен лаунчер. Вона робиться навмисно, і число формату росте.
2. Маніфест повністю розв'язаний. Якби встановлювач мав щось шукати, плагін мав би зробити це під час збирання.
3. Одна реалізація кожної речі. Одне злиття виводу плагінів, одне читання файла версії Mojang, один обчислювач правил. Кожен завантажувач проходить через той самий код, тож виправлення приземляється для всіх.
4. Розбір, а не перевірка. Тип декодує себе в нормальну форму. Жодних неперевірених приведень.
5. Функціональність і тестованість. Чисті функції скрізь, де можна. Розв'язувач це чиста логіка навколо одного мережевого виклику, і він приймає адресу API як параметр, щоб тести могли вказати йому на локальний сервер.

Межі це не лише проза. Вони записані як дані у scripts/architecture/rules.mjs, і npm run architecture не проходить, коли код їх лишає. Щоб додати залежність між пакетами, ви редагуєте цей файл, де його побачить рецензент.

Дві речі поза цим репозиторієм

Документи версій. Forge, NeoForge, Cleanroom і lwjgl3ify кожен встановлюється по-своєму химерно. Замість вчити opys кожного, кожне збирання один раз перетворене на документ у формі власного Mojang.

Вони опубліковані на harmoniya-net.github.io/metadata. Крейт завантажувача тоді малий: знайти збирання в індексі, забрати його документ, передати спільному коду. Генератор: harmoniya-net/metadata.

horno. Forge і NeoForge завершують встановлення латанням jar гри, що може статися лише на комп'ютері гравця. horno це мала програма на Java, яка робить це при першому запуску, потім запускає гру.

Документ версії називає його як головний клас, тож opys не має коду встановлення, специфічного для Forge. Джерело: harmoniya-net/horno.

Обидва можуть змінитися без коміта тут, що є однією з причин, чому існує матриця запуску нижче.

З чого почати

Щоб…	Почніть з
Додати завантажувач	crates/opys-forge, найпростіший, і packages/forge
Додати джерело модів	crates/opys-modrinth, crates/opys-links
Змінити злиття плагінів	assemble у crates/opys-dev/src/engine.rs
Змінити встановлення	crates/opys-runtime/src/phases, один модуль на фазу
Змінити формат	crates/opys-core, потім packages/core
Змінити командний рядок	packages/cli

Новий крейт або пакет також потребує запису в scripts/architecture/rules.mjs. Перевірка скаже вам, що ви пропустили.

Робота в репозиторії

npm run build              # аддон і кожен пакет
npm test                   # модульні тести JavaScript
cargo test --workspace     # тести Rust
npm run typecheck
npm run architecture       # перевірка меж
node scripts/smoke-napi.mjs   # аддон завантажується

Три важчі перевірки запускаються вручну:

• npm run test:int говорить зі справжніми сервісами Mojang, Forge, Adoptium і CurseForge. Йому потрібні мережа і CURSEFORGE_TOKEN.
• node docs/check-examples.mjs збирає кожну конфігурацію, показану на цьому сайті.
• Матриця запуску (scripts/launch-matrix) справді встановлює та запускає гру для списку версій і проходить, коли з'являється вікно і лишається відкритим. Зміна завантажувача, рантайму або horno не перевірена, поки не запущені випадки, яких вона торкається.

Написання цих сторінок

Сайт у docs/, зібраний на VitePress. docs/CONTRIBUTING.md має нотатки стилю. Коротка версія: пишіть для людини, ведіть з прикладу і кажіть чому.