liuzqk · liuzqk · May 24, 2026 · May 31, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,57 @@
+name: Bug report
+description: Report a reproducible ZeroEngine package bug
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: input
+    id: package
+    attributes:
+      label: Package
+      description: Package name, for example com.zerogamestudio.zeroengine.pathfinding2d.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version or commit
+      description: Package version or Git commit hash.
+    validations:
+      required: true
+  - type: input
+    id: unity
+    attributes:
+      label: Unity version
+      placeholder: 2022.3.62f1
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction steps
+      description: Provide the smallest steps that reproduce the issue.
+      placeholder: |
+        1. Create/open a Unity project
+        2. Install ...
+        3. Run ...
+        4. Observe ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs or screenshots
+      description: Paste Unity console errors, stack traces, or screenshots if useful.
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,33 @@
+name: Feature request
+description: Request a focused ZeroEngine package improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: input
+    id: package
+    attributes:
+      label: Package
+      description: Package name or area.
+    validations:
+      required: true
+  - type: textarea
+    id: workflow
+    attributes:
+      label: Workflow
+      description: What game development workflow should improve?
+    validations:
+      required: true
+  - type: textarea
+    id: current
+    attributes:
+      label: Current limitation
+      description: Why are existing APIs or tools insufficient?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed shape
+      description: Describe the smallest useful API, editor tool, or behavior change.
+    validations:
+      required: false
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,17 @@
+## Summary
+
+- 
+
+## Packages Touched
+
+- 
+
+## Verification
+
+- [ ] Ran focused Unity EditMode tests
+- [ ] Checked affected package manifests
+- [ ] Updated docs or README when behavior changed
+
+## Notes
+
+Describe any migration, compatibility, or downstream project impact.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,14 @@
+# Changelog
+
+ZeroEngine is developed as a multi-package repository. Package versions are
+tracked in each package's `package.json`.
+
+## Unreleased
+
+- Added root open-source project documentation.
+- Added contribution, support, and security guidance.
+- Declared MIT licensing for external reuse.
+- Normalized repository metadata for public UPM package consumption.
+
+For package-specific changes, inspect the package README, package version, and
+Git history for the relevant `com.zerogamestudio.*` directory.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,47 @@
+# Contributing to ZeroEngine
+
+ZeroEngine is a multi-package Unity repository. Keep changes scoped to the
+package and behavior you are improving.
+
+## Development Rules
+
+- Use Unity 2022.3 LTS unless a package explicitly documents a newer
+  requirement.
+- Prefer package-local changes over framework-wide abstractions.
+- Keep runtime code in `Runtime/` and editor-only code in `Editor/`.
+- Include `.meta` files whenever Unity assets, folders, asmdefs, samples, or
+  tests are added, moved, or deleted.
+- Do not edit generated Unity folders such as `Library/`, `Temp/`, or generated
+  IDE project files.
+
+## Package Metadata
+
+Each package should have a valid `package.json` with:
+
+- `name`, `version`, `displayName`, `description`, `unity`, and `author`.
+- `license` set to `MIT`.
+- `repository.url` pointing to `https://github.com/liuzqk/zeroengine.git` when
+  repository metadata is present.
+- `repository.directory` matching the top-level package folder when present.
+
+## Testing
+
+For runtime logic, add focused EditMode tests under the package `Tests/Editor/`
+folder. Use PlayMode tests only when Unity lifecycle, physics, scenes, prefabs,
+or coroutines are required.
+
+The GitHub workflow builds a temporary Unity project and runs EditMode tests
+with GameCI. Local verification can use Unity Test Runner with the smallest
+relevant package test assembly.
+
+## Pull Requests
+
+- Explain the user-facing reason for the change.
+- List the package or packages touched.
+- Include the verification you ran.
+- Keep unrelated formatting and refactors out of the PR.
+
+## License
+
+By contributing, you agree that your contribution is provided under the
+repository's MIT License.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZeroGameStudio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -0,0 +1,109 @@
+# ZeroEngine
+
+[![Unity Tests](https://github.com/liuzqk/zeroengine/actions/workflows/tests.yml/badge.svg)](https://github.com/liuzqk/zeroengine/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Unity 2022.3+](https://img.shields.io/badge/Unity-2022.3%2B-black.svg)](https://unity.com/releases/editor/archive)
+
+ZeroEngine is a modular Unity game framework maintained by ZeroGameStudio. It
+is organized as a set of Unity Package Manager packages so projects can depend
+on only the systems they need.
+
+The packages are developed against Unity 2022.3 LTS and are used by the POB
+Unity project for production gameplay tooling and runtime systems.
+
+## Why This Exists
+
+Unity game projects often rebuild the same infrastructure: singleton and event
+helpers, pooled runtime objects, save data, quests, platform navigation, UI
+panels, editor data browsers, and game-specific debugging tools. ZeroEngine
+keeps those systems in reusable packages with focused tests instead of burying
+them inside one game repository.
+
+## Package Highlights
+
+| Package | Purpose |
+| --- | --- |
+| `com.zerogamestudio.zeroengine.core` | Core helpers, logging, pooling, singleton patterns, and performance utilities. |
+| `com.zerogamestudio.zeroengine.data` | Data and stat systems for game configuration and runtime values. |
+| `com.zerogamestudio.zeroengine.data-toolkit` | Editor tooling for browsing, inspecting, and validating project data assets. |
+| `com.zerogamestudio.zeroengine.gameplay` | Reusable gameplay mechanics and trigger helpers. |
+| `com.zerogamestudio.zeroengine.narrative` | Quest and narrative runtime services. |
+| `com.zerogamestudio.zeroengine.pathfinding2d` | 2D platform navigation, graph generation, jump links, route costs, and diagnostics. |
+| `com.zerogamestudio.zeroengine.persistence` | Save and persistence infrastructure. |
+| `com.zerogamestudio.zeroengine.ui` | Runtime UI framework and toast notification systems. |
+| `com.zerogamestudio.analytics` | Self-hostable analytics and bug feedback SDK. |
+
+Additional packages in this repository cover AI, audio, combat, economy,
+input, localization, network, RPG, social, world, and editor dashboard systems.
+
+## Installation
+
+Add packages through Unity Package Manager using a Git URL with the package
+path you need:
+
+```text
+https://github.com/liuzqk/zeroengine.git?path=com.zerogamestudio.zeroengine.core#main
+```
+
+For example, a project `Packages/manifest.json` can pin several packages:
+
+```json
+{
+  "dependencies": {
+    "com.zerogamestudio.zeroengine.core": "https://github.com/liuzqk/zeroengine.git?path=com.zerogamestudio.zeroengine.core#main",
+    "com.zerogamestudio.zeroengine.pathfinding2d": "https://github.com/liuzqk/zeroengine.git?path=com.zerogamestudio.zeroengine.pathfinding2d#main",
+    "com.zerogamestudio.zeroengine.ui": "https://github.com/liuzqk/zeroengine.git?path=com.zerogamestudio.zeroengine.ui#main"
+  }
+}
+```
+
+Production projects should pin a tested commit hash instead of `#main`.
+
+## Repository Layout
+
+Each top-level `com.zerogamestudio.*` directory is a UPM package. Most packages
+follow the same structure:
+
+```text
+com.zerogamestudio.zeroengine.<module>/
+  Runtime/
+  Editor/
+  Tests/
+  Samples~/
+  package.json
+  README.md
+```
+
+Not every package has every folder; small runtime-only packages stay minimal.
+
+## Testing
+
+The repository includes a GitHub Actions workflow that builds a temporary Unity
+project and runs EditMode tests through GameCI.
+
+For local work, open a Unity 2022.3 project that references the package under
+test, then run the relevant EditMode tests from Unity Test Runner. Keep new
+tests narrow and package-scoped.
+
+## Support And Security
+
+- Use [GitHub issues](https://github.com/liuzqk/zeroengine/issues) for
+  reproducible bugs and focused feature requests.
+- See [SUPPORT.md](SUPPORT.md) for the information maintainers need.
+- See [SECURITY.md](SECURITY.md) for private security reporting guidance.
+
+## Current Production Users
+
+The POB Unity project depends on multiple ZeroEngine packages, including
+analytics, core, data, data-toolkit, economy, gameplay, narrative,
+pathfinding2d, persistence, and UI. This gives the packages a real production
+feedback loop while keeping reusable code outside the game-specific repository.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before opening issues or pull requests.
+Small, tested fixes are preferred over broad rewrites.
+
+## License
+
+ZeroEngine is available under the [MIT License](LICENSE).
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,29 @@
+# Security Policy
+
+## Supported Scope
+
+Security reports should focus on vulnerabilities in ZeroEngine package code,
+editor tooling, self-hosted analytics upload flows, and generated runtime
+configuration that could expose project data or execute unintended code.
+
+Unity project-specific content, game assets, and downstream game logic are
+outside this repository unless the issue is caused by reusable ZeroEngine code.
+
+## Reporting
+
+Do not open a public GitHub issue for security concerns. Send a private report
+to the maintainers with:
+
+- The affected package name and version or commit hash.
+- Reproduction steps.
+- Expected and observed impact.
+- Any relevant logs, stack traces, or minimal sample project details.
+
+If a private security advisory is available on the GitHub repository, prefer
+that channel.
+
+## Response Expectations
+
+Maintainers will triage reports based on reproducibility, affected packages,
+and severity. Fixes should include focused tests when the behavior is
+testable without exposing sensitive data.
diff --git a/SUPPORT.md b/SUPPORT.md
@@ -0,0 +1,19 @@
+# Support
+
+Use GitHub issues for reproducible bugs, documentation gaps, and focused
+feature requests.
+
+For bug reports, include:
+
+- Package name and version or commit hash.
+- Unity version.
+- Platform.
+- Minimal reproduction steps.
+- Console errors or relevant logs.
+- Whether the issue reproduces in a clean Unity project.
+
+For feature requests, describe the game development workflow being improved
+and why existing package APIs are insufficient.
+
+Project-specific integration questions for private games may be closed if they
+cannot be answered from reusable ZeroEngine code.
diff --git a/com.zerogamestudio.analytics/package.json b/com.zerogamestudio.analytics/package.json
@@ -1,8 +1,14 @@
 {
-    "name": "com.zerogamestudio.analytics",
-    "version": "1.2.2",
-    "displayName": "ZGS Analytics",
-    "description": "ZeroGameStudio 游戏分析 SDK，支持自建 ClickHouse 数据平台",
-    "unity": "2021.3",
-    "dependencies": {}
-}
+  "name": "com.zerogamestudio.analytics",
+  "version": "1.2.2",
+  "displayName": "ZGS Analytics",
+  "description": "ZeroGameStudio 游戏分析 SDK，支持自建 ClickHouse 数据平台",
+  "unity": "2021.3",
+  "dependencies": {},
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/liuzqk/zeroengine.git",
+    "directory": "com.zerogamestudio.analytics"
+  }
+}