Skip to content

LIBRARY.md

Latest commit

 

History

History
102 lines (67 loc) · 9.36 KB

LIBRARY.md

File metadata and controls

102 lines (67 loc) · 9.36 KB
Raw

GameKit Library 契约

GameKit 1.0.0 只通过一个不易冲突的 Defold 命名空间导出：/gamekit/。Library 项目的 game.project 声明 [library] include_dirs = gamekit；消费者应使用带版本的 release ZIP URL，并执行 Project ▸ Fetch Libraries。

安装

在消费者项目的 [project] 中加入不可变 GameKit release URL，以及 GameKit 的三个核心依赖：

[project]
dependencies#0 = https://github.com/Lodrasyll/Lodra-DefGameDevKit/releases/download/1.0.0/gamekit-1.0.0.zip
dependencies#1 = https://github.com/Insality/defold-lang/archive/refs/tags/5.zip
dependencies#2 = https://github.com/britzl/defold-orthographic/archive/refs/tags/3.6.3.zip
dependencies#3 = https://github.com/Insality/defold-tweener/archive/refs/tags/6.zip

上面的 URL 是已发布 1.0.0 的不可变规范地址，已经由全新消费工作区完成公开下载与 Defold 依赖解压验证。稳定集成契约绝不能使用会移动的 branch URL。Defold 不会递归安装 Library Project 自身声明的依赖 URL：消费者的 game.project 必须列出 GameKit，以及所选 GameKit 模块需要的每个依赖。上面三个 URL 是独立消费者实测使用的核心运行集合。只有使用 gamekit.ui.druid_adapter 时，才增加 Defold Event 21 和 Druid 1.2.6：

dependencies#4 = https://github.com/Insality/defold-event/archive/refs/tags/21.zip
dependencies#5 = https://github.com/Insality/druid/archive/refs/tags/1.2.6.zip

参考游戏需要演示可选 Druid adapter，因此声明全部五项。复制这份矩阵时，所有 URL 都要固定到不可变 tag/archive，并保持依赖顺序。

获取 Library 后，在运行时验证精确版本：

local version = require("gamekit.version")

assert(version.STRING == "1.0.0")
assert(version.is_compatible(1, 0))

公共边界

受支持的运行时命名空间是 gamekit.*。gamekit/README.md 记录的模块在整个 1.x major 发布线中属于公共接口。/game/、/main/、/input/、/assets/、根构建设置和 demo Bootstrap 均属于宿主项目，绝不导出。

以下导出子树具有更窄的契约：

  • gamekit/editor/ 只用于 Editor。Library 中的命令会被自动发现，但生命周期 hook 不会；如果消费者采用 GameKit 内容约定，应在根 /hooks.editor_script 中组合 require("gamekit.editor.hooks")。
  • gamekit/tests/ 是可执行的一致性测试代码，不是游戏运行时 API。
  • gamekit/fx/benchmark.lua 和 gamekit/fx/html5_benchmark.settings 是按需启用的基准支持，不属于正常启动行为。
  • 具体游戏内容、音频 clip 和 demo Sprite 必须留在消费者项目。GameKit Audio/FX 接受已注册 URL/target，不拥有游戏专用媒体资源。

每个导出的 Defold 资源只能引用其他 /gamekit/ 资源、/builtins/，或 GameKit 明确锁定 release 的依赖根目录：/druid/、/event/、/lang/、/orthographic/、/tweener/。python tools/package_gamekit.py 会在生成 release ZIP 前强制检查 allowlist，并拒绝 /game/、/main/、/assets/ 等宿主内容路径。

宿主集成责任

GameKit 有意不替换消费者项目的 Bootstrap。宿主负责：

  • game.project 中的 Bootstrap、input binding 和可选 /gamekit/render/gamekit.renderc 选择；
  • 构造和注册服务实例；
  • 具体 Collection Proxy registry、持久 GUI URL、Sound component URL 与 camera bridge；
  • 按宿主内容布局保存 Story、locale、character、scene 和生成数据库数据；
  • 根 hooks.editor_script，包括多个 Library 都提供 hook 时的组合顺序。

本仓库中的完整 demo 是参考组合。只复制游戏实际需要的宿主资源；不要把 /main/ 或 /game/ 误认为隐藏的 Library 要求。

版本、升级与弃用

  • MAJOR.MINOR.PATCH 遵循语义化版本。
  • 1.x 的 minor 与 patch release 不会有意破坏已记录公共 API、SPI 或持久化数据语义。
  • 不兼容的公共 API、SPI 或持久化数据变更必须提升 major 版本。
  • 计划移除的公共 API 必须至少保留一个 minor release；在可行时输出明确迁移警告，并出现在 changelog 的已弃用部分。
  • Save payload schema 版本独立于 GameKit package 版本。消费者必须提供逐版迁移，绝不能只根据 gamekit.version 推断存档兼容性。

发布与验收命令

python tools/validate_gamekit.py --json
python tools/validate_public_api.py
python -m unittest discover -s tools -p "test_*.py" -v
python tools/package_gamekit.py
python tools/verify_library_consumer.py --bob-jar C:\path\to\bob.jar --java C:\path\to\java.exe
python tools/verify_library_benchmark.py --bob-jar C:\path\to\bob.jar --java C:\path\to\java.exe --samples 10
python tools/verify_library_size.py --bob-jar C:\path\to\bob.jar --java C:\path\to\java.exe

如果已安装的 Defold Editor 把 Bob class 存在应用 JAR 中而不是独立 bob.jar，使用 --bob-classpath C:\path\to\defold-editor.jar；验证器会调用官方 com.dynamo.bob.Bob 入口。两种 Bob 来源必须且只能选择一种。验证器默认使用 headless engine variant，因为该 fixture 是非交互 CI smoke；可传入 --variant debug 或 --variant release 增加 graphical/release-engine 门禁。

使用 --platform <Bob-platform> --variant release --build-only 可以交叉编译目标 bundle，而不尝试执行外部平台程序。Defold 1.13.1 的 release build-only 当前已通过 Linux x86_64/arm64、macOS x86_64/arm64、wasm-web、Android arm64 AAB 和 iOS x86_64/arm64 unsigned IPA。Build-only 绝不会自动把 Runtime 矩阵行升级为通过；仍需在真实目标运行。

Android 可以追加 --bundle-format aab，只生成并签名 AAB，避免 Bob 继续从 AAB 派生 Universal APK。--bundle-format 是 Bob 官方参数；它只证明相应发布包格式成功生成，不替代真实设备安装、生命周期、GPU、音频和存储验证。

在 Windows 主机交叉生成 iOS unsigned IPA 时追加 --windows-ios-compat。验证器会用已安装的 .NET SDK 在临时目录构建受限 cp.exe/zip.exe（CI 锁定 .NET 8；本地允许 .NET 5 以上 SDK，并只在临时项目副本中匹配该 SDK 的 major），只支持 Bob 1.13.1 实际调用的 cp -r 与 zip -qr，并且只对该次 Bob 子进程临时扩展 PATH。该选项不提供 Apple 签名，也不替代 macOS/iOS runtime 验证。

并列工作区 E:\EmptyProJTest 是真正独立、可以单独打开的 Defold 消费项目。其源 game.project 使用规范 1.0.0 Release URL；本机发布验证器把项目复制到系统临时目录，并且只在临时副本中把该 URL 替换为 localhost 上的待测归档。CI 使用 --generate-consumer 在临时目录生成等价项目，不依赖本机绝对路径。Bob 随后解析 GameKit 和三个显式 core 依赖，构建并运行项目；只有检测到 [GameKit][LibraryConsumer] runtime smoke passed marker 才接受归档。Windows x86_64 headless 门禁已在 Defold 1.13.1 通过，并在该全新进程中执行 Foundation save fixture。仓库根 tests/ 已移除，不再维护第二套重复 fixture。

追加 --include-optional-ui 会在临时消费者中显式加入 Event 21 与 Druid 1.2.6，并实际加载 gamekit.ui.druid_adapter；它用于验证五依赖 UI 组合，不会改变仓库中的 fixture 或核心三依赖最小集合。

gamekit/API_BASELINE.json 是机器可读的 1.x major 发布线兼容底线。打包命令会在写归档前验证每个锁定模块/导出符号，并确认 baseline 的 API line 与当前 major 一致。新增导出不会使门禁失败；移除符号必须先完成规定的弃用周期，并通过下一个 major 版本把 baseline 更新为显式发布决策。

包体验证器会构建并运行其他条件完全相同的空白 A/B 消费者。B 侧只加载 gamekit.version 和 gamekit.core.event，因此结果是最小编译入口基线，不代表全部服务或 Renderer 功能。默认使用 --variant headless；graphical variant 仅用于诊断，当前即使在不含 GameKit 的 A 侧也会复现环境级启动 assertion。

同一 release ZIP 已完成 Linux x86_64/arm64、macOS x86_64/arm64、wasm-web、Android arm64 AAB 与 iOS x86_64/arm64 unsigned IPA 的 release build-only。Windows 上构建 iOS 时，--windows-ios-compat 会在临时目录编译只实现 Bob 所需 cp -r、zip -qr 的受限兼容程序；它不修改系统 PATH，也不提供签名或 runtime 证明。可选 UI 组合也已通过 build-only。

Graphical debug/release 消费者和可选 Druid/Event native-extension 的实际启动，当前都会在 GameKit Lua 执行前触发 Defold 1.13.1 的 script_crash.cpp assertion。包体验证器已用 no-GameKit graphical baseline 复现同一问题，证明本机触发源不是 GameKit core。这些路径仍是独立环境/兼容门禁；不得把通过的 build 或 headless core 结果外推为 graphical/custom-engine runtime 通过。

许可证与分发义务

发布归档包含根 LICENSE.md（MIT）和 THIRD_PARTY_NOTICES.md。GameKit 的三个核心依赖和两个可选 UI 依赖均锁定 release，但由消费者项目通过 Defold/Bob 单独下载；消费者仍负责在分发物中保留精确的上游许可证材料。打包验证器强制归档恰好包含一个非空根许可证，但不判断特定分发方式的法律适用性。