UnityStarter

A modular Unity project with a reusable framework layer, organised after Unreal Engine's gameplay model. GameplayFramework follows the Actor, Pawn, Controller and GameMode split; GameplayAbilities and GameplayTags provide the ability and tag primitives those contracts build on.

The repository targets medium and large Unity projects that keep one codebase for years. What that gives a project:

• Each module is a separate UPM package with its own assembly definition, so a project references only what it uses and unused modules never enter the compile or the build.
• Logic that can stay engine-free does, so it runs in EditMode tests, headless processes and CLI tools.
• Module boundaries are held by tests (engine seam, package graph), not only by convention.
• Build pipeline, analyzers and maintenance tools live in the repository and version together with the code.

English | 简体中文

[!NOTE] If you find this project helpful, please consider giving it a star ⭐ Thank you!

Table of Contents

• Table of Contents
• How to use this repository
• What Is Inside
• Architecture Principles
  • Project Ownership Model
• Repository Layout
• Module Map
  • Gameplay
  • AI
  • Data, Assets And Content
  • Runtime Infrastructure
  • Build, Tools And Quality
• Networking Status
• Build, CI/CD And Project Tooling
  • Build is project-owned infrastructure
  • Tools for derived projects
• Getting Started
  • Requirements
  • First Run
  • Using Individual Modules
• Technology Stack
• Documentation
• Validation Status
• Related Projects

How to use this repository

UnityStarter provides the structure a project needs before gameplay code exists: asset ownership, separated gameplay architecture, data-driven content, module boundaries, build automation, analyzers and maintenance tools.

Use the repository in two ways:

• As a project template: open UnityStarter/ in Unity, rename it with the bundled tools, and let the project-owned Assets/Build/ layer evolve with your game.
• As a package (UPM) (recommended): move out folders under CycloneGames and add them from Package Manager. Packages are independent, so a project imports only the ones it references; each declares its own dependencies.

What Is Inside

UnityStarter combines a reusable CycloneGames framework layer, a Unity project template, a project-owned Build/CI module, standalone maintenance tools, bilingual documentation, and validation-oriented analyzer support.

The Module Map is the primary index for gameplay, content, UI/input, AI, runtime infrastructure, build tooling, and experimental networking packages.

Item	Detail
Unity project root	UnityStarter/
Unity version source	UnityStarter/ProjectSettings/ProjectVersion.txt
CycloneGames module folders	UnityStarter/Assets/ThirdParty/CycloneGames/
Assembly definitions	Package and project assembly boundaries are declared by .asmdef files under UnityStarter/Assets/.
Analyzer rules	20+ implemented CycloneGames.Analyzers rules, staged project-wide by Assets/Default.ruleset (Unity auto-applies a root-level ruleset with this exact name)
Standalone tools	Go tools with Windows executables under Tools/Executable/Windows/

Architecture Principles

• Pure C# first where it matters: core contracts avoid leaking UnityEngine types when logic should remain testable in CLI, EditMode, headless simulation, or future adapters.
• Unity as the integration layer: MonoBehaviour, ScriptableObject, editor tools, scene bindings, and assets bridge into runtime systems without owning complex domain rules.
• Optional integrations stay isolated: DI containers, tween engines, scene navigation, serializers, transports, and hot-update backends live behind dedicated integration assemblies.
• Performance is a design constraint: hot paths aim for zero-GC or low-GC behavior, predictable ownership, reusable buffers, and explicit lifecycle cleanup.
• Build is project-owned: Assets/Build/ is expected to travel with derived projects and change with product requirements.
• Docs are part of the API: long-lived modules are expected to maintain README.md and README.SCH.md together.

Project Ownership Model

This diagram is a repository ownership and module responsibility map, not a runtime dependency graph. It shows which parts are expected to evolve with a derived game, which parts are reusable framework modules, and which parts are optional or experimental integrations.

flowchart TD
  subgraph ProjectOwned["Project-owned template layer"]
    StarterAssets["Assets/UnityStarter/\nScenes, project assets, composition"]
    BuildLayer["Assets/Build/\nBuild and CI entry points"]
    ProjectTools["Tools/\nRename, cleanup, maintenance utilities"]
  end

  subgraph FrameworkModules["Reusable CycloneGames modules"]
    Gameplay["Gameplay\nGameplayFramework, Abilities, Tags, RPGFoundation"]
    Content["Content\nAssetManagement, DataTable, Localization, Audio"]
    Presentation["Presentation/Input\nUIFramework, InputSystem, DeviceFeedback"]
    AI["AI\nBehaviorTree, AIPerception"]
    Infrastructure["Runtime Infrastructure\nFactory, Logger, DeterministicMath, Hash, IO"]
  end

  subgraph OptionalIntegrations["Optional / experimental integrations"]
    Networking["Networking packages\nExperimental until end-to-end validated"]
    HotUpdate["Hot-update build hooks\nHybridCLR, YooAsset, Addressables when installed"]
  end

  ProjectTools --> StarterAssets
  ProjectTools --> BuildLayer
  StarterAssets --> Gameplay
  StarterAssets --> Content
  StarterAssets --> Presentation
  StarterAssets --> AI
  Gameplay --> Infrastructure
  Content --> Infrastructure
  Presentation --> Content
  AI --> Infrastructure
  BuildLayer -. detects/invokes .-> HotUpdate
  Gameplay -. optional bridge .-> Networking
  AI -. optional bridge .-> Networking

  class StarterAssets,BuildLayer,ProjectTools projectNode
  class Gameplay,Content,Presentation,AI frameworkNode
  class Infrastructure infraNode
  class Networking,HotUpdate optionalNode

  classDef projectNode fill:#E6F4FF,stroke:#6B9BC3,color:#263238,stroke-width:1px
  classDef frameworkNode fill:#FFF1D9,stroke:#C99745,color:#263238,stroke-width:1px
  classDef infraNode fill:#F4F4F5,stroke:#9CA3AF,color:#263238,stroke-width:1px
  classDef optionalNode fill:#E8F8F5,stroke:#67A69A,color:#263238,stroke-width:1px,stroke-dasharray: 5 4

Repository Layout

<repo-root>/
  README.md / README.SCH.md              # Root bilingual overview
  Docs/                                  # Cross-module guides
  Tools/                                 # Standalone maintenance utilities
  UnityStarter/                          # Unity project root
    Analyzers/CycloneGames.Analyzers/    # Roslyn analyzer project
    Assets/Build/                        # Project-owned Build/CI module
    Assets/ThirdParty/CycloneGames/      # Reusable CycloneGames framework modules
    Assets/UnityStarter/                 # Template project scenes and game-side assets
    Packages/                            # Unity package manifest and lock file
    ProjectSettings/                     # Unity settings, including version source

Module Map

Recommended first pass: GameplayFramework, AssetManagement, GameplayAbilities, GameplayTags, DataTable, and Build.

Gameplay

Module	Role	Docs
GameplayFramework	Actor/Pawn/Controller/GameMode structure, gameplay lifecycle, camera flow, and scene-flow foundation.	README
GameplayFramework.AssetManagement	Resolves WorldSettings references through AssetManagement with explicit handle ownership.	README
GameplayFramework.Factory	Actor creation and release through the Factory lifetime model.	README
GameplayFramework.GameplayAbilities	Exposes ability systems from framework actors and initialises actor information.	README
GameplayFramework.GameplayTags	Resolves and modifies tag containers attached to framework actors.	README
GameplayAbilities	GAS-style data-driven ability, attribute, effect, cost, cooldown, and cue system with an explicit authority/replica role and authoritative AuthorityOnly execution boundary. The optional Networking integration provides authority-activation protocol building blocks.	README
Choreography	Engine-free action presentation scheduling for animation, audio, VFX, gameplay-event markers, and preload coordination.	Folder
GameplayTags	Hierarchical tags, generated constants, query helpers, editor tooling, and integration points.	README
RPGFoundation	RPG movement and interaction foundations that can integrate with other gameplay packages.	README
RPGFoundation.Interaction.GameplayFramework	Framework actor binding for RPG interaction.	README
RPGFoundation.Interaction.DeterministicMath	Fixed-point authority integration for RPG interaction.	README
RPGFoundation.Interaction.DeterministicMath.GameplayFramework	Framework actor bridge for deterministic interaction authority state.	README
UIFramework	Window management, UI flow, presentation patterns, and asset-backed UI loading that delegates handle ownership and eviction decisions to AssetManagement's segmented-LRU (SLRU) cache.	README
UIFramework.Localization	Binds Localization to UI windows, with an optional TextMeshPro slice for per-locale layout snapshots.	README
Foundation2D	2D foundation package and samples for derived projects.	Folder

AI

Module	Role	Docs
BehaviorTree	Behavior tree runtime, graph editor, tests, and a data-oriented Burst path for homogeneous agents.	README
BehaviorTree.Spatial	Optional bridge that publishes nearest-neighbour results into blackboard slots.	README
BehaviorTree.Perception	Optional bridge that publishes a sensor's nearest target to the blackboard, with a multi-sensor aggregator.	README
BehaviorTree.EnvQuery	Optional bridge that runs an environment query and publishes the best candidate.	README
AIPerception	Jobs and Burst based perception: sensors, memory, transition events, team attitudes.	README
AIEnvQuery	Candidate generation and weighted scoring for position choice. Engine-free core.	README
AIResources	Claim table for resources that admit one owner at a time, with priority preemption and lease expiry.	README

Data, Assets And Content

Module	Role	Docs
AssetManagement	Interface-first asset loading abstraction with bounded segmented-LRU (SLRU) caching, CacheRetention policies/scheduler, provider abstraction, diagnostics, and async loading flows.	README
AtlasPipeline	Sprite import and SpriteAtlas V2 generation with incremental indexing and build-time validation.	README
DataTable	Designer-facing data pipeline with optional Luban, MessagePack, and asset-management bridges.	README
GameplayTags.DataTable	DataTable integration for GameplayTags authoring and loading.	README
Choreography.AssetManagement	Optional Choreography resource provider bridge for CycloneGames.AssetManagement.	Folder
Choreography.CycloneAudio	Optional Choreography audio provider bridge for CycloneGames.Audio.	Folder
Localization	Validated locale fallback, partitioned text/assets, transactional catalogs, and editor translation workflows.	README
Audio	Audio management layer with async loading, runtime ownership, and platform-aware policies.	README
Audio.Localization	Keeps the audio voice locale in step with the Localization locale.	README
FontAssets	CJK, Latin, symbol, and number font assets.	Folder

Runtime Infrastructure

Module	Role	Docs
Factory	Factory and object pooling module with DI-friendly use and ECS/DOD variants.	README
Logging	Unity-free logging contracts, channels, severity, process-writer routing, and a safe null writer.	README
Logging Pipeline	Unity-free bounded processing, filtering, sinks, file output, statistics, and deterministic shutdown.	README
Logging Unity	Optional Unity lifecycle, settings, Console sink, Editor tooling, and build integration for the logging pipeline.	README
DeterministicMath	Fixed-point deterministic math for replay, simulation, and lockstep-friendly systems.	README
Hash	Deterministic hashing primitives for manifests, protocol checks, IDs, and consistency.	README
IO	Managed file and path utilities for Unity-aware foundation modules.	README
Persistence	Unity-free, bounded, versioned single-record orchestration with strict Record V1 integrity checks and serializer/storage-neutral contracts.	README
Persistence.SystemIO	Optional System.IO storage and Unity persistentDataPath composition, with bounded reads and atomic commit behavior.	README
Persistence.VYaml	Optional generated-resolver VYaml codec for readable UTF-8 persistence payloads.	README
Persistence.MessagePack	Optional assembly-gated MessagePack codec source; inactive until its pinned binary, analyzer, and Unity bridge are installed.	README
InputSystem	Validated YAML input authoring with prioritized mapping contexts, per-player device ownership, local multiplayer, binding profiles, Editor tooling, and opt-in integrations.	README
InputSystem.AssetManagement	Optional physical package-loading bridge between InputSystem, AssetManagement, and VContainer.	README
DeviceFeedback	Haptics, vibration, rumble, and device-light feedback abstractions.	README
Settings	Unity-free cloned settings state with defaults, validation, forward migration, isolated snapshots, and typed post-commit notifications.	README
Settings.Persistence	Optional integration that composes Settings state and migration with one Persistence Store without coupling either Core.	README
Utility	Common Unity utility components and helpers.	Folder
Cheat	Build-gated internal cheat command system with VitalRouter integration.	README
EventBus	Zero-allocation event bus with pooled subscription handles, a bounded cross-thread ring, and optional R3, UniTask, VitalRouter and Logging adapters.	README
Scheduling	Bounded cooperative work scheduling with lane priority, soft frame budgets, fault isolation and deterministic shutdown.	README
Spatial	Uniform spatial hash grid for broad-phase queries, with handle lifetime, structure-of-arrays storage and a single-writer thread model.	README

Build, Tools And Quality

Area	Role	Docs
Build	Project-owned player build pipeline, version info, optional hot-update hooks, and CI-facing methods.	README
Tools	Go tools for project rename, package trimming, cleanup, file trees, and asset processing.	README
Analyzers	Unity-focused Roslyn analyzer rules for performance, safety, async, and conventions. The project-wide severity policy lives in Assets/Default.ruleset.	README

Networking Status

The networking layer is an experimental foundation. Production adoption requires end-to-end validation with the selected transport, serializer, authority model, reconnect flow, platform target, and gameplay replication policy.

Module	Role	Status
Networking	Transport-neutral contracts, message catalogs, protocol manifests, sessions, replication, security, serializers, adapters, and diagnostics.	Experimental. README
GameplayFramework.Networking	Session bridge, actor migration serialization, authority roles, and observer resolution.	Experimental. README
GameplayAbilities.Networking	Command, prediction, state replication, cue and endpoint contracts for GameplayAbilities.	Experimental. README
AIPerception.Networking	Perception event, snapshot, memory, authority, and host-migration contracts.	Experimental. README
BehaviorTree.Networking	Behavior tree replication profiles, authority helpers, snapshots, and blackboard deltas.	Experimental. README
RPGFoundation.Movement.Networking	Movement input, snapshot, correction, teleport, authority transfer, validation, history, and reconciliation contracts.	Experimental. README
RPGFoundation.Interaction.Networking	Interaction DTOs, vector conversion, authority validation bridge, and message catalog registration.	Experimental. README
RPGFoundation.Projectile.Networking	Projectile protocol metadata, DTOs, validation helpers, prediction reconciliation, snapshot history, and authority bridge contracts.	Experimental. README

Build, CI/CD And Project Tooling

Build is project-owned infrastructure

UnityStarter/Assets/Build/ is project-owned infrastructure. Product projects can adjust scenes, version prefixes, output layout, hot-update assembly lists, platform signing, and release rules there.

When a developer derives a new game from UnityStarter and runs rename_project, the Build layer remains part of the new project and should continue to be maintained there.

The Build module includes:

• BuildData ScriptableObject configuration.
• Git or Perforce revision metadata through Build.VersionControl.Editor; batch-mode and release builds require one, while only an interactive Development build may use the explicit LocalDevelopment fallback.
• Editor menu items and command-line player build entry points.
• Optional integrations for HybridCLR, Obfuz, YooAsset 3, and Addressables; missing packages do not break the core build assembly.
• Cheat define control for internal builds.
• A single CI entry point: Build.Pipeline.Editor.BuildEntryPoints.RunCommandLine.

Minimal command shape:

Unity -batchmode -quit -projectPath UnityStarter \
  -executeMethod Build.Pipeline.Editor.BuildEntryPoints.RunCommandLine \
  -buildTarget Win64 \
  -pipelineProfile Assets/UnityStarter/Editor/Build/BuildData.asset \
  -pipelineOutput Build/Windows/Release/UnityStarter.exe \
  -pipelineClean

The Build README includes deeper configuration notes, hot-update workflows, and CI examples.

Tools for derived projects

The Tools/ directory contains standalone Go utilities:

Tool	Purpose
rename_project	Rename a derived UnityStarter project safely and repeatedly.
remove_unity_packages	Remove unnecessary packages from manifest.json.
unity_project_full_clean	Clean Unity caches, generated projects, and build artifacts.
audio_volume_normalizer	Normalize audio loudness with category-aware targets.
texture_channel_packer	Pack texture channels for mask maps and similar workflows.
unity_video_webm_converter	Convert videos to Unity-friendly VP8 WebM.
generate_file_tree	Generate Markdown directory trees for documentation.

See Tools README for usage details.

Getting Started

Requirements

• The Unity version recorded in UnityStarter/ProjectSettings/ProjectVersion.txt.
• Git or Perforce is required for automatic version metadata in batch-mode and release builds; only an interactive Development build may use deterministic LocalDevelopment fallback metadata.

First Run

git clone https://github.com/MaiKuraki/UnityStarter.git

1. Open UnityStarter/ in Unity Hub.
2. Open UnityStarter/Assets/UnityStarter/Scenes/Scene_Launch.unity.
3. Read GameplayFramework to understand the high-level architecture.
4. Read Build before changing build settings or CI methods.
5. If you are creating a new project from this template, run Tools/Executable/Windows/rename_project.exe and review Tools README.

Using Individual Modules

Copy a module folder from UnityStarter/Assets/ThirdParty/CycloneGames/ into your project, then inspect its package.json, .asmdef files, README, dependencies, and optional Integrations/ folders. There is no all-or-nothing import: a project takes the packages it calls and the packages those declare as dependencies. Some modules are self-contained; others depend on shared CycloneGames packages or Unity packages.

Technology Stack

Versions should be checked in UnityStarter/Packages/manifest.json, UnityStarter/Packages/packages-lock.json, and UnityStarter/Packages/nuget-packages/InstalledPackages/.

Area	Examples
Async and reactive	com.cysharp.unitask, com.cysharp.r3, NuGet R3
Routing and data	jp.hadashikick.vitalrouter.unity, jp.hadashikick.vyaml, NuGet VitalRouter, NuGet VYaml
Unity performance stack	Burst, Collections, Mathematics, Profiling Core, Memory Profiler, Profile Analyzer
Unity gameplay stack	Input System, Cinemachine, URP, TextMeshPro, UGUI, Splines
UI and debug helpers	SoftMask, UIEffect, CompositeCanvasRenderer, UnityDebugSheet, InGameDebugConsole, uPalette
Build and analysis	Scriptable Build Pipeline, NuGetForUnity, Roslyn packages for CycloneGames analyzers
Optional integrations	VContainer, PrimeTween, Navigathena, Luban, MessagePack, HybridCLR, YooAsset, Addressables, Obfuz, Mirror, Mirage

Documentation

Location	Purpose
UnityStarter/Assets/ThirdParty/CycloneGames/*/README.md	Module-level documentation for long-lived packages.
UnityStarter/Assets/Build/README.md	Build pipeline, hot update, optional packages, and CI.
UnityStarter/Analyzers/CycloneGames.Analyzers/README.md	Analyzer rules, build instructions, and activation guidance.
Tools/README.md	Standalone project maintenance tools.
Docs/AudioBestPractices/AudioBestPractices.md	Audio import and runtime audio guidance.
DeepWiki	Generated codebase overview.

Validation Status

Validation runs through Unity and the test runner in the project.

• Open UnityStarter/ and confirm the Console has no errors after import.
• Run the EditMode suites of the modules you changed. The full suite is available through Test Runner, or in batch mode:

Unity -batchmode -nographics -projectPath UnityStarter -runTests   -testPlatform EditMode -testFilter CycloneGames -testResults results.xml -logFile test.log

• Two guard suites protect repository-wide invariants and should stay green:
  • CoreSeamGuardTests checks that engine-free Core assemblies stay free of Unity types, disk IO and host compilation symbols.
  • PackageReferenceGuardTests checks that every cross-package assembly reference is either declared in package.json or gated by a capability symbol.
• Build the analyzers with dotnet build UnityStarter/Analyzers/CycloneGames.Analyzers/CycloneGames.Analyzers.csproj -c Release.
• Use Build > Pipeline > Print Selected Profile before changing BuildData or CI settings.
• Networking modules remain experimental; production use needs end-to-end validation against the chosen transport, serializer and authority model.

Related Projects

• Rhythm Pulse - Rhythm game mechanics collection
• Unity GAS Sample - GAS demonstration project

---

License: MIT