Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ jobs:
python-version: "3.13"
- name: Validate package layout and Python sources
run: python .infernux-dev/validate.py
- name: Check validation contracts
run: python -m unittest discover -s tests
- name: Build and verify deterministic package bytes
run: |
mkdir -p dist/repro
Expand Down Expand Up @@ -62,9 +64,7 @@ jobs:
env:
GH_TOKEN: ${{ github.token }}
run: |
if gh release view "${GITHUB_REF_NAME}" >/dev/null 2>&1; then
gh release upload "${GITHUB_REF_NAME}" "dist/${PACKAGE_NAME}" dist/infernux-plugin-release.json --clobber
else
gh release create "${GITHUB_REF_NAME}" "dist/${PACKAGE_NAME}" dist/infernux-plugin-release.json \
--verify-tag --generate-notes
fi
# Published reference/version pairs are immutable. A duplicate tag
# must fail instead of replacing users' installed archive baseline.
gh release create "${GITHUB_REF_NAME}" "dist/${PACKAGE_NAME}" dist/infernux-plugin-release.json \
--verify-tag --generate-notes
65 changes: 47 additions & 18 deletions .infernux-dev/validate.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
from __future__ import annotations

import ast
import json
from pathlib import Path

Expand All @@ -17,28 +18,56 @@
for path in ("README.md", "README.zh-CN.md", "LICENSE", "package", "package.py"):
if not (ROOT / path).exists():
raise SystemExit(f"Missing template entry: {path}")
for path in sorted((*PACKAGE.joinpath("runtime").rglob("*.py"), *PACKAGE.joinpath("editor").rglob("*.py"))):
compile(path.read_text(encoding="utf-8"), str(path), "exec")
runtime_sources = tuple(PACKAGE.joinpath("runtime").rglob("*.py"))
editor_sources = tuple(PACKAGE.joinpath("editor").rglob("*.py"))
if not any("InxComponent" in path.read_text(encoding="utf-8") for path in runtime_sources):
raise SystemExit("Template runtime has no InxComponent example")
if not any("InxPreload" in path.read_text(encoding="utf-8") for path in runtime_sources):
raise SystemExit("Template runtime has no Player-safe InxPreload example")
if not any("InxPreload" in path.read_text(encoding="utf-8") for path in editor_sources):
raise SystemExit("Template editor has no editor-owned InxPreload example")
for path in runtime_sources:


def module_names(root):
names = set()
for path in root.rglob("*.py"):
parts = path.relative_to(root).with_suffix("").parts
if parts[-1] == "__init__":
parts = parts[:-1]
if parts:
names.add(".".join(parts))
return names


runtime_root = PACKAGE / "runtime"
editor_root = PACKAGE / "editor"
# Namespace directories alone do not execute editor code and may be shared.
editor_only_modules = module_names(editor_root) - module_names(runtime_root)
editor_imports = {"infernux.engine.ui", "Infernux.engine.ui"} | editor_only_modules

for path in sorted((*runtime_root.rglob("*.py"), *editor_root.rglob("*.py"))):
source = path.read_text(encoding="utf-8")
if "example_plugin_editor" in source or "Infernux.engine.ui" in source:
raise SystemExit(f"Runtime source imports Editor code: {path.relative_to(PACKAGE)}")
compile(source, str(path), "exec")
if not path.is_relative_to(runtime_root):
continue
tree = ast.parse(source, filename=str(path))
package_parts = path.relative_to(runtime_root).parent.parts
for node in ast.walk(tree):
if isinstance(node, ast.Import):
imports = [alias.name for alias in node.names]
elif isinstance(node, ast.ImportFrom):
if node.level:
if node.level > len(package_parts):
continue # An invalid relative import is a Python runtime error.
prefix = package_parts[:len(package_parts) - node.level + 1]
suffix = node.module.split(".") if node.module else ()
module = ".".join((*prefix, *suffix))
else:
module = node.module or ""
imports = [module, *(f"{module}.{alias.name}" for alias in node.names)]
else:
continue
if any(
name == editor or name.startswith(editor + ".")
for name in imports for editor in editor_imports
):
raise SystemExit(f"Runtime source imports Editor code: {path.relative_to(PACKAGE)}:{node.lineno}")
for english in PACKAGE.joinpath("plugin_pages").glob("*.md"):
if english.name.endswith(".zh-CN.md"):
continue
localized = english.with_name(f"{english.stem}.zh-CN.md")
if not localized.is_file():
raise SystemExit(f"Missing zh-CN page: {localized.name}")
source = english.read_text(encoding="utf-8")
for required_topic in ("runtime/", "editor/", "plugin_pages/", "add_cleanup", "Export InxPackage"):
if required_topic not in source:
raise SystemExit(f"Plugin tutorial is missing {required_topic!r}: {english.name}")
print("Template layout and Python sources are valid.")
print("Package layout and Python sources are valid.")
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ flowchart LR

`package.py` uses only the Python standard library, so packaging does not require an Infernux installation. Your repository may use CMake, Gradle, Cargo, npm, or another build system; copy only the files users need at runtime into `package/`.

The included Python starter requires Infernux 0.4.1 and uses the lowercase `infernux` package. Keep the manifest's engine range aligned with the APIs your plugin actually uses.

Inside an Infernux project, the selected folder is already the package root: select it in Project/File Manager, right click, and choose **Export InxPackage...**. The installed Plugins page contains the full tutorial, including lifecycle ownership, hot reload, Player component registration, large imports, and an Editor-only Flask tool window.

## Package layout
Expand Down
2 changes: 2 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,8 @@ flowchart LR

`package.py` 只使用 Python 标准库,打包时不需要安装 Infernux。仓库可以自由使用 CMake、Gradle、Cargo、npm 或其他构建工具;只需把用户运行插件时真正需要的文件放进 `package/`。

模板中的 Python 示例需要 Infernux 0.4.1,并使用小写的 `infernux` 包。插件清单中的引擎版本范围应与实际使用的 API 保持一致。

在 Infernux 项目中,被选中的文件夹本身就是包根:在 Project/File Manager 中选中它,右键选择**导出 InxPackage...**。安装后插件页面中的完整教程会说明生命周期所有权、热重载、Player 组件注册、大型包导入以及仅 Editor 使用的 Flask 独立工具窗口。

## 目录结构
Expand Down
6 changes: 3 additions & 3 deletions package/editor/your_studio/example_plugin_editor/panel.py
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
"""Example panel available only inside the editor."""

from Infernux.engine.interaction import PanelInteractionDescriptor
from Infernux.engine.ui.editor_panel import EditorPanel
from Infernux.engine.ui.panel_registry import editor_panel
from infernux.engine.interaction import PanelInteractionDescriptor
from infernux.engine.ui.editor_panel import EditorPanel
from infernux.engine.ui.panel_registry import editor_panel


@editor_panel(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

from importlib import import_module

from Infernux.lifecycle import InxPreload, PreloadContext
from infernux.lifecycle import InxPreload, PreloadContext


class ExamplePluginEditorPreload(InxPreload):
Expand Down
2 changes: 1 addition & 1 deletion package/inx_package.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@
"reference": "your-studio/example-plugin",
"name": "Example Plugin",
"version": "0.1.0",
"engine": ">=0.4,<0.5",
"engine": ">=0.4.1,<0.5",
"intro": "A minimal Infernux runtime and editor extension."
}
4 changes: 2 additions & 2 deletions package/runtime/your_studio/example_plugin/component.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
"""Example gameplay component shipped to the player build."""

from Infernux.components import InxComponent, serialized_field
from Infernux.lib import Vector3, quatf
from infernux.components import InxComponent, serialized_field
from infernux.lib import Vector3, quatf


class ExampleRotator(InxComponent):
Expand Down
2 changes: 1 addition & 1 deletion package/runtime/your_studio/example_plugin/preload.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
"""Early lifecycle for services that must exist in Editor and Player."""

from Infernux.lifecycle import InxPreload, PreloadContext
from infernux.lifecycle import InxPreload, PreloadContext


class ExamplePluginPreload(InxPreload):
Expand Down
95 changes: 95 additions & 0 deletions tests/test_release_immutability.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
"""Run the real release shell step against a local GitHub CLI boundary."""
from pathlib import Path
import os
import shutil
import subprocess
import tempfile
import unittest


ROOT = Path(__file__).resolve().parents[1]


class ReleaseImmutabilityTests(unittest.TestCase):
def setUp(self):
workspace = tempfile.TemporaryDirectory()
self.addCleanup(workspace.cleanup)
self.root = Path(workspace.name)
if os.name == "nt":
git = shutil.which("git")
self.assertIsNotNone(git, "Git for Windows is required to run the release shell step")
self.bash = Path(git).resolve().parents[1] / "bin/bash.exe"
else:
self.bash = shutil.which("bash")
self.assertTrue(self.bash and Path(self.bash).is_file(), "Bash is required for release workflow tests")
workflow = (ROOT / ".github/workflows/validate.yml").read_text(encoding="utf-8")
publish = workflow.split(" - name: Publish GitHub Release assets\n", 1)[1]
script = publish.split(" run: |\n", 1)[1]
(self.root / "release.sh").write_text(
"set -e\n" + "\n".join(line[10:] for line in script.splitlines()) + "\n",
encoding="utf-8",
)
(self.root / "bin").mkdir()
(self.root / "dist").mkdir()
(self.root / "published").mkdir()
(self.root / "dist/studio.demo.inxpkg").write_bytes(b"candidate archive")
(self.root / "dist/infernux-plugin-release.json").write_bytes(b"candidate manifest")
# The adapter implements both the current and legacy CLI routes. An
# overwrite attempt would change the baseline and make the test fail.
adapter = '''#!/usr/bin/env bash
set -eu
printf '%s\\n' "$*" >> calls.txt
case "$1:$2" in
release:view)
test -f published/archive.inxpkg
;;
release:create)
if test -f published/archive.inxpkg; then
echo "release already exists" >&2
exit 23
fi
cp "$4" published/archive.inxpkg
cp "$5" published/manifest.json
;;
release:upload)
cp "$4" published/archive.inxpkg
cp "$5" published/manifest.json
;;
*) exit 24 ;;
esac
'''
path = self.root / "bin/gh"
path.write_text(adapter, encoding="utf-8")
path.chmod(0o755)

def publish(self):
environment = dict(os.environ, GITHUB_REF_NAME="v0.1.0", PACKAGE_NAME="studio.demo.inxpkg")
return subprocess.run(
[str(self.bash), "--noprofile", "--norc", "-c",
'export PATH="$PWD/bin:$PATH"; exec bash release.sh'],
cwd=self.root, env=environment, capture_output=True, text=True,
)

def test_duplicate_release_fails_without_overwriting_either_asset(self):
archive = self.root / "published/archive.inxpkg"
manifest = self.root / "published/manifest.json"
archive.write_bytes(b"original archive")
manifest.write_bytes(b"original manifest")
result = self.publish()
self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr)
self.assertEqual(archive.read_bytes(), b"original archive")
self.assertEqual(manifest.read_bytes(), b"original manifest")

def test_new_release_publishes_the_archive_and_matching_manifest(self):
result = self.publish()
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)
self.assertEqual((self.root / "published/archive.inxpkg").read_bytes(), b"candidate archive")
self.assertEqual((self.root / "published/manifest.json").read_bytes(), b"candidate manifest")
self.assertEqual(
(self.root / "calls.txt").read_text(encoding="utf-8").splitlines(),
["release create v0.1.0 dist/studio.demo.inxpkg dist/infernux-plugin-release.json --verify-tag --generate-notes"],
)


if __name__ == "__main__":
unittest.main()
Loading
Loading