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 targets medium-to-large Unity productions with long-term iteration needs: 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.

The value is a reusable engineering foundation covering ownership, testability, optional integrations, build configuration, editor tooling, and documentation.

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

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

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 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.	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 segmented-LRU (SLRU) cache.	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 bounded segmented-LRU (SLRU) 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
Choreography.AssetManagement	Optional Choreography resource provider bridge for CycloneGames.AssetManagement.	README
Choreography.CycloneAudio	Optional Choreography audio provider bridge for CycloneGames.Audio.	README
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
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

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
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. 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.
Docs/Networking/GameJamLanMultiplayerGuide.md	LAN multiplayer planning guide.
Docs/Networking/NetworkSecurityGuide.md	Networking security boundaries, production composition, ownership, platform requirements, and verification.
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 > Pipeline > Print Selected Profile 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