A production-oriented, modular Unity foundation project and reusable framework base, informed by Unreal Engine architecture. Its GameplayFramework applies Unreal-style gameplay organization around Actor, Pawn, Controller, and GameMode, while Gameplay Abilities and GameplayTags provide GAS-like ability and tagging primitives for explicit gameplay contracts.

UnityStarter is not intended to be a beginner-first, plug-and-play framework for small projects. It is designed as a stable, maintainable engineering foundation for medium-to-large Unity productions that expect long-term iteration: explicit ownership boundaries, performance-conscious runtime systems, engine-agnostic core layers, and project-owned build/tooling infrastructure.

English | 简体中文

Note

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

Table of Contents

• Table of Contents
• Why UnityStarter
• 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

Why UnityStarter

UnityStarter is for developers and teams who want production-grade Unity structure from the start: predictable asset ownership, separated gameplay architecture, data-driven content, explicit module boundaries, build automation, analyzers, and maintenance tools.

Use the repository in two practical 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): move out folders under CycloneGames, add from PackageManager.

Its value is the reusable engineering foundation around ownership, testability, optional integrations, build configuration, editor tooling, and documentation.

What Is Inside

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

For module-level details, use the Module Map. It 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
Current Unity version	2022.3.62f3
CycloneGames module folders	30+ under UnityStarter/Assets/ThirdParty/CycloneGames/
Assembly definitions	140+ .asmdef files under UnityStarter/Assets/
Analyzer rules	20+ implemented CycloneGames.Analyzers rules
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

Loading

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

Use this section as a navigation 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
GameplayAbilities	GAS-style data-driven ability, attribute, effect, cost, cooldown, and cue system.	README
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
UIFramework	Window management, UI flow, presentation patterns, and asset-backed UI loading that delegates handle ownership and eviction decisions to AssetManagement's W-TinyLFU cache; UIFramework does not maintain a separate CacheRetention policy layer.	README
Foundation2D	2D foundation package and samples for derived projects.	Folder

AI

Module	Role	Docs
BehaviorTree	Behavior tree runtime, editor support, tests, and data-oriented runtime pieces.	README
AIPerception	Jobs/Burst-oriented perception, sensor queries, spatial structures, and low-GC runtime flow.	README

Data, Assets And Content

Module	Role	Docs
AssetManagement	Interface-first asset loading abstraction with W-TinyLFU-inspired caching, CacheRetention policies/scheduler, provider abstraction, diagnostics, and async loading flows.	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
Localization	String tables, locale fallback, asset variants, and hot-reload-oriented loading.	README
Audio	Audio management layer with async loading, runtime ownership, and platform-aware policies.	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
Logger	Thread-safe logging with levels, filtering, background processing, and Unity integration.	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
InputSystem	Reactive input wrapper with YAML config, editor tooling, local multiplayer/multi-device support, automatic device detection, device auto-switching, context stacks, and device pairing.	README
DeviceFeedback	Haptics, vibration, rumble, and device-light feedback abstractions.	README
Services	Unity-facing service helpers for derived projects.	Folder
Utility	Common Unity utility components and helpers.	Folder
Cheat	Build-gated internal cheat command system with VitalRouter integration.	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.	README

Networking Status

The networking layer is present and documented, but it is not yet project-validated end to end. It should be treated as an experimental foundation until it has been tested with a real 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
GameplayAbilities.Networking	Ability activation, effect replication, attribute/tag sync, prediction keys, reconnect state, and security policy bridge.	Experimental. README
GameplayFramework.Networking	Session bridge, actor migration serialization, authority roles, and observer resolution.	Experimental. README
GameplayTags.Networking	Manifest handshakes and tag payload wrappers.	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

Build, CI/CD And Project Tooling

Build is project-owned infrastructure

UnityStarter/Assets/Build/ is intentionally project-owned. It is not a frozen low-level package because real products need to adjust scenes, version prefixes, output layout, hot-update assembly lists, platform signing, and release rules.

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-based version information through Build.VersionControl.Editor.
• Editor menu items and command-line player build entry points.
• Optional reflection-detected integrations for HybridCLR, Obfuz, YooAsset, Addressables, and Buildalon.
• Cheat define control for internal builds.
• CI-facing methods such as Build.Pipeline.Editor.BuildScript.PerformBuild_CI.

Minimal command shape:

Unity -batchmode -quit -projectPath UnityStarter \
  -executeMethod Build.Pipeline.Editor.BuildScript.PerformBuild_CI \
  -buildTarget StandaloneWindows64 \
  -output Build/Windows/UnityStarter.exe \
  -clean

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

• 2022.3.62f3+
• Git / Perforce / SVN, used by the Build module for automatic version information.

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. 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 in this checkout
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.
Docs/Networking/GameJamLanMultiplayerGuide.md	LAN multiplayer planning guide.
DeepWiki	Generated codebase overview.

Validation Status

The repository contains tests and analyzer rules, but the safest validation path is still Unity-driven:

• Open the project in Unity and confirm it compiles without Console errors.
• Run relevant EditMode tests for any module you change.
• Build the analyzer project with dotnet build UnityStarter/Analyzers/CycloneGames.Analyzers/CycloneGames.Analyzers.csproj -c Release.
• Use Build > Print Debug Info before changing BuildData or CI settings.
• Treat Networking as experimental until you complete real multiplayer validation in your target environment.

Related Projects

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

---

License: MIT