theone-unity-standards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TheOne Studio Unity Development Standards

TheOne Studio Unity开发标准

⚠️ Unity 6 (C# 9): All patterns and examples are compatible with Unity 6, which uses C# 9. No C# 10+ features are used.

⚠️ Unity 6（C# 9）： 所有模式和示例均兼容使用C# 9的Unity 6，未使用C# 10及以上版本的特性。

Skill Purpose

技能用途

This skill enforces TheOne Studio's comprehensive Unity development standards with CODE QUALITY FIRST:

Priority 1: Code Quality & Hygiene (MOST IMPORTANT)

Nullable reference types, access modifiers, fix all warnings
Throw exceptions (never log errors)
TheOne.Logging.ILogger (runtime, no guards, no prefixes, no constructor logs) vs Debug.Log (editor only)
readonly/const, nameof, using directive scope
No inline comments (use descriptive names)

Priority 2: Modern C# Patterns

LINQ over loops, extension methods, expression bodies
Null-coalescing operators, pattern matching
Modern C# features (records, init, with)

Priority 3: Unity Architecture

VContainer + SignalBus OR TheOne.DI + Publisher/Subscriber
Data Controllers pattern (NEVER direct data access)
Resource management, UniTask async patterns

Priority 4: Performance & Review

LINQ optimization, allocation prevention
Code review guidelines

本技能以代码质量优先为原则，强制执行TheOne Studio的全套Unity开发标准：

优先级1：代码质量与规范（最重要）

可空引用类型、访问修饰符、修复所有警告
抛出异常（绝不记录错误日志）
TheOne.Logging.ILogger（运行时使用，无需防护、无需前缀、不在构造函数中记录）与Debug.Log（仅编辑器使用）的区别
readonly/const、nameof、using指令作用域
禁止行内注释（使用具有描述性的命名）

优先级2：现代C#模式

优先使用LINQ而非循环、扩展方法、表达式体
空合并运算符、模式匹配
现代C#特性（records、init、with）

优先级3：Unity架构

VContainer + SignalBus 或 TheOne.DI + 发布/订阅模式
数据控制器模式（绝不直接访问数据）
资源管理、UniTask异步模式

优先级4：性能与审查

LINQ优化、避免内存分配
代码审查指南

When This Skill Triggers

本技能适用场景

Writing or refactoring Unity C# code
Implementing Unity features with dependency injection
Working with events and signals
Accessing or modifying game data
Reviewing code changes or pull requests
Setting up project architecture

编写或重构Unity C#代码
使用依赖注入实现Unity功能
处理事件与信号
访问或修改游戏数据
审查代码变更或合并请求
搭建项目架构

Quick Reference Guide

快速参考指南

What Do You Need Help With?

您需要哪方面的帮助？

Priority	Task	Reference
🔴 PRIORITY 1: Code Quality (Check FIRST)
1	Nullable types, access modifiers, warnings, exceptions	Quality & Hygiene ⭐
1	TheOne.Logging.ILogger (no guards, no prefixes, no constructor logs) vs Debug.Log	Quality & Hygiene ⭐
1	readonly/const, nameof, using scope, no inline comments	Quality & Hygiene ⭐
🟡 PRIORITY 2: Modern C# Patterns
2	LINQ, extension methods, var usage	LINQ Patterns
2	Expression bodies, null-coalescing, pattern matching	Modern C# Features
2	Records, init, with expressions	Modern C# Features
🟢 PRIORITY 3: Unity Architecture
3	VContainer dependency injection	VContainer DI
3	SignalBus event system	SignalBus Events
3	Data Controllers pattern (NEVER direct data access)	Data Controllers
3	Service/Bridge/Adapter integration	Integration Patterns
3	TheOne.DI + Publisher/Subscriber alternative	TheOne Framework
3	UniTask async/await patterns	UniTask Patterns
🔵 PRIORITY 4: Performance & Review
4	Performance, LINQ optimization, allocations	Performance
4	Architecture review (DI, events, controllers)	Architecture Review
4	C# quality review (LINQ, null handling)	C# Quality
4	Unity-specific review (components, lifecycle)	Unity Specifics
4	Performance review (allocations, hot paths)	Performance Review

优先级	任务	参考文档
🔴 优先级1：代码质量（首先检查）
1	可空类型、访问修饰符、警告、异常	质量与规范 ⭐
1	TheOne.Logging.ILogger（无需防护、无需前缀、不在构造函数中记录）与Debug.Log的区别	质量与规范 ⭐
1	readonly/const、nameof、using作用域、禁止行内注释	质量与规范 ⭐
🟡 优先级2：现代C#模式
2	LINQ、扩展方法、var的使用	LINQ模式
2	表达式体、空合并、模式匹配	现代C#特性
2	Records、init、with表达式	现代C#特性
🟢 优先级3：Unity架构
3	VContainer依赖注入	VContainer DI
3	SignalBus事件系统	SignalBus事件
3	数据控制器模式（绝不直接访问数据）	数据控制器
3	服务/桥接/适配器集成	集成模式
3	TheOne.DI + 发布/订阅替代方案	TheOne框架
3	UniTask async/await模式	UniTask模式
🔵 优先级4：性能与审查
4	性能、LINQ优化、内存分配	性能优化
4	架构审查（DI、事件、控制器）	架构审查
4	C#质量审查（LINQ、空值处理）	C#质量
4	Unity专属审查（组件、生命周期）	Unity特性
4	性能审查（内存分配、热路径）	性能审查

🔴 CRITICAL: Code Quality Rules (CHECK FIRST!)

🔴 关键：代码质量规则（首先检查！）

⚠️ MANDATORY QUALITY STANDARDS

⚠️ 强制质量标准

ALWAYS enforce these BEFORE writing any code:

Enable nullable reference types - No nullable warnings allowed
Use least accessible access modifier - private by default
Fix ALL warnings - Zero tolerance for compiler warnings
Throw exceptions for errors - NEVER log errors, throw exceptions
TheOne.Logging.ILogger for runtime - No conditional guards (#if), no prefixes ([prefix]), NEVER in constructors; Debug.Log ONLY for editor scripts
Use readonly for fields - Mark fields that aren't reassigned
Use const for constants - Constants should be const, not readonly
Use nameof for strings - Never hardcode property/parameter names
Using directive in deepest scope - Method-level using when possible
No inline comments - Use descriptive names; code should be self-explanatory

Example: Enforce Quality First

csharp

// ✅ EXCELLENT: All quality rules enforced
#nullable enable // 1. Nullable enabled

public sealed class PlayerService
{
    private readonly TheOne.Logging.ILogger logger;
    private const int MaxHealth = 100;

    public PlayerService(TheOne.Logging.ILogger logger)
    {
        this.logger = logger;
    }

    public Player GetPlayer(string id)
    {
        using System.Text.Json;

        return players.TryGetValue(id, out var player)
            ? player
            : throw new KeyNotFoundException($"Player not found: {id}");
    }

    private void LoadGameData()
    {
        this.logger.Info("Game data loaded");
    }
}

#if UNITY_EDITOR
public class EditorTool
{
    public void Process()
    {
        Debug.Log("Processing..."); // 5. Debug.Log OK in editor
    }
}
#endif

在编写任何代码之前，必须强制执行以下规则：

启用可空引用类型 - 不允许存在可空警告
使用最严格的访问修饰符 - 默认使用private
修复所有警告 - 零容忍编译器警告
错误场景抛出异常 - 绝不记录错误日志，直接抛出异常
运行时使用TheOne.Logging.ILogger - 无需条件防护（#if）、无需前缀（[prefix]）、绝不在构造函数中使用；仅编辑器脚本可使用Debug.Log
字段使用readonly - 标记不会被重新赋值的字段
常量使用const - 常量应使用const而非readonly
字符串使用nameof - 绝不硬编码属性/参数名称
using指令使用最小作用域 - 尽可能在方法级别使用using
禁止行内注释 - 使用具有描述性的命名；代码应自解释

示例：优先保障代码质量

csharp

// ✅ EXCELLENT: All quality rules enforced
#nullable enable // 1. Nullable enabled

public sealed class PlayerService
{
    private readonly TheOne.Logging.ILogger logger;
    private const int MaxHealth = 100;

    public PlayerService(TheOne.Logging.ILogger logger)
    {
        this.logger = logger;
    }

    public Player GetPlayer(string id)
    {
        using System.Text.Json;

        return players.TryGetValue(id, out var player)
            ? player
            : throw new KeyNotFoundException($"Player not found: {id}");
    }

    private void LoadGameData()
    {
        this.logger.Info("Game data loaded");
    }
}

#if UNITY_EDITOR
public class EditorTool
{
    public void Process()
    {
        Debug.Log("Processing..."); // 5. Debug.Log OK in editor
    }
}
#endif

⚠️ Unity Architecture Rules (AFTER Quality)

⚠️ Unity架构规则（质量达标后）

Choose ONE Framework Stack

选择一套框架栈

Choose ONE stack per project:

Option 1: VContainer + SignalBus

✅ VContainer for dependency injection
✅ SignalBus for events
✅ [Preserve] attribute on constructors

Option 2: TheOne.DI + Publisher/Subscriber

✅ TheOne.DI wrapper
✅ IPublisher<T>/ISubscriber<T> for events
✅ [Inject] attribute on constructors

Universal Rules (Both Stacks):

✅ Use Data Controllers (NEVER direct data access)
✅ Use UniTask for async operations
✅ Unload assets in Dispose
✅ TheOne.Logging.ILogger for runtime (no guards, no prefixes, no constructor logs), Debug.Log for editor only

每个项目选择一套框架栈：

选项1：VContainer + SignalBus

✅ 使用VContainer进行依赖注入
✅ 使用SignalBus处理事件
✅ 构造函数添加[Preserve]属性

选项2：TheOne.DI + 发布/订阅

✅ 使用TheOne.DI封装
✅ 使用IPublisher<T>/ISubscriber<T>处理事件
✅ 构造函数添加[Inject]属性

通用规则（适用于两套栈）：

✅ 使用数据控制器（绝不直接访问数据）
✅ 使用UniTask进行异步操作
✅ 在Dispose中卸载资源
✅ 运行时使用TheOne.Logging.ILogger（无需防护、无需前缀、不在构造函数中记录），仅编辑器使用Debug.Log

Brief Examples

简短示例

🔴 Code Quality First

🔴 代码质量优先

csharp

// ✅ EXCELLENT: Quality rules enforced
#nullable enable

public sealed class PlayerController
{
    private readonly TheOne.Logging.ILogger logger;
    private const int MaxRetries = 3;

    public PlayerController(TheOne.Logging.ILogger logger)
    {
        this.logger = logger;
    }

    public Player LoadPlayer(string id)
    {
        if (!File.Exists(id))
            throw new FileNotFoundException($"Player file not found: {id}");

        this.logger.Info($"Loading player {id}");
        return DeserializePlayer(id);
    }
}

#if UNITY_EDITOR
public class EditorHelper
{
    public void Log() => Debug.Log("Editor only"); // Debug.Log OK in editor
}
#endif

csharp

// ✅ EXCELLENT: Quality rules enforced
#nullable enable

public sealed class PlayerController
{
    private readonly TheOne.Logging.ILogger logger;
    private const int MaxRetries = 3;

    public PlayerController(TheOne.Logging.ILogger logger)
    {
        this.logger = logger;
    }

    public Player LoadPlayer(string id)
    {
        if (!File.Exists(id))
            throw new FileNotFoundException($"Player file not found: {id}");

        this.logger.Info($"Loading player {id}");
        return DeserializePlayer(id);
    }
}

#if UNITY_EDITOR
public class EditorHelper
{
    public void Log() => Debug.Log("Editor only"); // Debug.Log OK in editor
}
#endif

🟡 Modern C# Patterns

🟡 现代C#模式

csharp

// ✅ GOOD: LINQ instead of loops
var activeEnemies = allEnemies.Where(e => e.IsActive).ToList();

// ✅ GOOD: Expression bodies
public int Health => this.currentHealth;

// ✅ GOOD: Null-coalescing
var name = playerName ?? "Unknown";

// ✅ GOOD: Pattern matching
if (obj is Player player) player.TakeDamage(10);

csharp

// ✅ GOOD: LINQ instead of loops
var activeEnemies = allEnemies.Where(e => e.IsActive).ToList();

// ✅ GOOD: Expression bodies
public int Health => this.currentHealth;

// ✅ GOOD: Null-coalescing
var name = playerName ?? "Unknown";

// ✅ GOOD: Pattern matching
if (obj is Player player) player.TakeDamage(10);

Unity Architecture (VContainer)

Unity架构（VContainer）

csharp

using UnityEngine.Scripting;
using VContainer.Unity;

public sealed class GameService : IInitializable, IDisposable
{
    private readonly SignalBus signalBus;
    private readonly LevelDataController levelController;

    [Preserve]
    public GameService(SignalBus signalBus, LevelDataController levelController)
    {
        this.signalBus = signalBus;
        this.levelController = levelController;
    }

    void IInitializable.Initialize()
    {
        this.signalBus.Subscribe<WonSignal>(this.OnWon);
    }

    void IDisposable.Dispose()
    {
        this.signalBus.TryUnsubscribe<WonSignal>(this.OnWon);
    }
}

csharp

using UnityEngine.Scripting;
using VContainer.Unity;

public sealed class GameService : IInitializable, IDisposable
{
    private readonly SignalBus signalBus;
    private readonly LevelDataController levelController;

    [Preserve]
    public GameService(SignalBus signalBus, LevelDataController levelController)
    {
        this.signalBus = signalBus;
        this.levelController = levelController;
    }

    void IInitializable.Initialize()
    {
        this.signalBus.Subscribe<WonSignal>(this.OnWon);
    }

    void IDisposable.Dispose()
    {
        this.signalBus.TryUnsubscribe<WonSignal>(this.OnWon);
    }
}

Unity Architecture (TheOne.DI)

Unity架构（TheOne.DI）

csharp

public sealed class GameService : IAsyncEarlyLoadable, IDisposable
{
    private readonly IPublisher<WonSignal> publisher;
    private IDisposable? subscription;

    [Inject]
    public GameService(
        IPublisher<WonSignal> publisher,
        ISubscriber<WonSignal> subscriber)
    {
        this.publisher = publisher;
        this.subscription = subscriber.Subscribe(this.OnWon);
    }

    public void Dispose()
    {
        this.subscription?.Dispose();
    }
}

csharp

public sealed class GameService : IAsyncEarlyLoadable, IDisposable
{
    private readonly IPublisher<WonSignal> publisher;
    private IDisposable? subscription;

    [Inject]
    public GameService(
        IPublisher<WonSignal> publisher,
        ISubscriber<WonSignal> subscriber)
    {
        this.publisher = publisher;
        this.subscription = subscriber.Subscribe(this.OnWon);
    }

    public void Dispose()
    {
        this.subscription?.Dispose();
    }
}

Code Review Checklist

代码审查清单

Quick Validation (before committing)

快速验证（提交前）

Common Mistakes to Avoid

需避免的常见错误

❌ DON'T:

❌ 禁止操作：

Ignore nullable warnings → Enable #nullable and fix all warnings
Log errors instead of throwing → Throw exceptions for errors
Use Debug.Log in runtime code → Use TheOne.Logging.ILogger (Debug.Log is editor only)
Add conditional guards to logs → ILogger handles #if internally
Add manual log prefixes → ILogger handles [prefix] automatically
Log in constructors → Never log in constructors (keep fast/side-effect free)
Use logger?.Method() → Use logger.Method() (DI guarantees non-null)
Add verbose logs → Keep only necessary logs
Skip access modifiers → Always use least accessible (private default)
Hardcode strings → Use nameof() for property/parameter names
Leave fields mutable → Use readonly/const where possible
Use Zenject → Use VContainer
Use MessagePipe directly → Use SignalBus
Access data models directly → Use Controllers
Forget to unsubscribe from signals → Implement IDisposable
Add inline comments → Use descriptive names instead

忽略可空警告 → 启用#nullable并修复所有警告
记录错误而非抛出异常 → 错误场景直接抛出异常
运行时代码使用Debug.Log → 运行时使用TheOne.Logging.ILogger（Debug.Log仅编辑器可用）
日志添加条件防护 → ILogger内部已处理#if逻辑
手动添加日志前缀 → ILogger自动处理[prefix]
构造函数中记录日志 → 绝不在构造函数中记录日志（保持快速、无副作用）
使用logger?.Method() → 使用logger.Method()（DI保证非空）
添加冗余日志 → 仅保留必要日志
省略访问修饰符 → 始终使用最严格的访问修饰符（默认private）
硬编码字符串 → 属性/参数名称使用nameof()
字段保持可变 → 尽可能使用readonly/const
使用Zenject → 改用VContainer
直接使用MessagePipe → 改用SignalBus
直接访问数据模型 → 使用控制器
忘记取消信号订阅 → 实现IDisposable
添加行内注释 → 使用具有描述性的命名

✅ DO:

✅ 推荐操作：

Enable nullable reference types (#nullable enable)
Throw exceptions for errors (never log errors)
Use TheOne.Logging.ILogger for runtime (no guards, no prefixes, no constructor logs)
Use logger.Method() directly (no null-conditional, DI guarantees non-null)
Debug.Log for editor only (#if UNITY_EDITOR)
Use least accessible modifiers (private by default)
Use descriptive names (no inline comments)
Use nameof() for string literals
Use readonly/const for immutable fields
Use VContainer or TheOne.DI for dependency injection
Use SignalBus or Publisher/Subscriber for all events
Use Controllers for all data access
Always implement IDisposable and unsubscribe
Add [Preserve] or [Inject] to prevent code stripping
Use LINQ for collection operations

启用可空引用类型（#nullable enable）
错误场景抛出异常（绝不记录错误日志）
运行时使用TheOne.Logging.ILogger（无需防护、无需前缀、不在构造函数中记录）
直接使用logger.Method()（无需空值条件，DI保证非空）
仅编辑器使用Debug.Log（需#if UNITY_EDITOR）
使用最严格的访问修饰符（默认private）
使用具有描述性的命名（无需行内注释）
字符串字面量使用nameof()
不可变字段使用readonly/const
依赖注入使用VContainer或TheOne.DI
事件处理使用SignalBus或发布/订阅模式
数据访问仅通过控制器
始终实现IDisposable并取消订阅
添加[Preserve]或[Inject]属性防止代码剥离
集合操作使用LINQ

Review Severity Levels

审查严重级别

🔴 Critical (Must Fix)

🔴 严重（必须修复）

Nullable warnings not fixed - Enable #nullable and fix all warnings
Logging errors instead of throwing - Use throw, not log for errors
Debug.Log in runtime code - Must use TheOne.Logging.ILogger (Debug.Log = editor only)
Conditional guards on logs - ILogger handles #if internally, remove guards
Manual log prefixes - ILogger handles [prefix] automatically, remove prefixes
Logging in constructors - Never log in constructors (keep fast/side-effect free)
Null-conditional on logger - Use logger.Method() not logger?.Method()
Missing access modifiers - All members must have explicit modifiers
Compiler warnings ignored - Zero tolerance for warnings
Inline comments - Use descriptive names instead
Using Zenject instead of VContainer
Using MessagePipe instead of SignalBus
Direct data access (not using Controllers)
Memory leaks (not unsubscribing)
Missing IDisposable implementation

未修复可空警告 → 启用#nullable并修复所有警告
记录错误而非抛出异常 → 使用throw而非日志记录错误
运行时代码使用Debug.Log → 必须改用TheOne.Logging.ILogger（Debug.Log仅编辑器可用）
日志添加条件防护 → ILogger内部已处理#if，移除防护
手动添加日志前缀 → ILogger自动处理[prefix]，移除前缀
构造函数中记录日志 → 绝不在构造函数中记录日志（保持快速、无副作用）
日志使用空值条件 → 使用logger.Method()而非logger?.Method()
缺少访问修饰符 → 所有成员必须显式添加修饰符
忽略编译器警告 → 零容忍警告
存在行内注释 → 使用具有描述性的命名替代
使用Zenject而非VContainer
使用MessagePipe而非SignalBus
直接访问数据（未使用控制器）
内存泄漏（未取消订阅）
未实现IDisposable

🟡 Important (Should Fix)

🟡 重要（应修复）

Missing readonly/const - Fields should be readonly/const when possible
Hardcoded strings - Use nameof() for property/parameter names
Using directives not in deepest scope - Method-level using when possible
Verbose unnecessary logs - Keep only necessary logs
Verbose code instead of LINQ
Missing [Preserve] or [Inject] attribute
Performance issues in hot paths
Missing unit tests for business logic
No XML documentation on public APIs

缺少readonly/const → 尽可能为字段添加readonly/const
硬编码字符串 → 属性/参数名称使用nameof()
Using指令未使用最小作用域 → 尽可能在方法级别使用using
冗余日志 → 仅保留必要日志
使用冗余代码而非LINQ
缺少[Preserve]或[Inject]属性
热路径存在性能问题
业务逻辑缺少单元测试
公共API缺少XML文档

🟢 Nice to Have (Suggestion)

🟢 建议（优化项）

Could use expression body
Could use null-conditional
Could use pattern matching
Could improve naming
Could simplify with modern C# features

可使用表达式体
可使用空值条件
可使用模式匹配
可优化命名
可使用现代C#特性简化代码

Detailed References

详细参考文档

C# Coding Standards

C#编码标准

LINQ Patterns - LINQ, extension methods, var usage
Modern C# Features - Expression bodies, null-coalescing, pattern matching, records
Quality & Hygiene - Nullable types, access modifiers, logging, exceptions
Performance Optimizations - Unity patterns, LINQ performance

LINQ模式 - LINQ、扩展方法、var的使用
现代C#特性 - 表达式体、空合并、模式匹配、records
质量与规范 - 可空类型、访问修饰符、日志、异常
性能优化 - Unity模式、LINQ性能

Unity Architecture

Unity架构

VContainer DI - Complete VContainer dependency injection guide
SignalBus Events - SignalBus event system patterns
Data Controllers - Data Controller implementation
Integration Patterns - Service/Bridge/Adapter for third-party SDKs
TheOne Framework - TheOne.DI + Publisher/Subscriber alternative
UniTask Patterns - Async/await with UniTask

VContainer DI - 完整VContainer依赖注入指南
SignalBus事件 - SignalBus事件系统模式
数据控制器 - 数据控制器实现
集成模式 - 第三方SDK的服务/桥接/适配器集成
TheOne框架 - TheOne.DI + 发布/订阅替代方案
UniTask模式 - 使用UniTask实现Async/await

Code Review

代码审查

Architecture Review - VContainer, SignalBus, Controllers violations
C# Quality Review - LINQ, expression bodies, null handling
Unity Specifics Review - Component access, lifecycle, cleanup
Performance Review - Allocations, LINQ in hot paths

架构审查 - VContainer、SignalBus、控制器违规检查
C#质量审查 - LINQ、表达式体、空值处理检查
Unity特性审查 - 组件访问、生命周期、清理检查
性能审查 - 内存分配、热路径LINQ检查

Summary

总结

This skill provides comprehensive Unity development standards for TheOne Studio:

C# Excellence: Modern, concise, professional C# code
Unity Architecture: VContainer+SignalBus OR TheOne.DI+Publisher patterns
Code Quality: Enforced quality, hygiene, and performance rules
Code Review: Complete checklist for pull request reviews

Use the Quick Reference Guide above to navigate to the specific pattern you need.

本技能为TheOne Studio提供了全面的Unity开发标准：

C#卓越性：现代、简洁、专业的C#代码
Unity架构：VContainer+SignalBus 或 TheOne.DI+发布者模式
代码质量：强制执行质量、规范和性能规则
代码审查：完整的合并请求审查清单

使用上方的快速参考指南，可快速导航至所需的特定模式。