UnityStarter

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 | 简体中文

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.

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.

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

AI

Data, Assets And Content

Runtime Infrastructure

Build, Tools And Quality

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.

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:

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/.

Documentation

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