Unity prototype sạch ngay từ ngày đầu: thư mục, assembly boundary và quy tắc đặt tên cho indie team

Giới thiệu

Bài này là hướng dẫn thực hành cho các indie team muốn bắt đầu một Unity prototype "sạch" ngay từ ngày đầu — nghĩa là cấu trúc thư mục có tính mở rộng, ranh giới assembly rõ ràng giữa runtime/editor/tests, quy ước đặt tên nhất quán và cách hạn chế dùng Resources bừa bãi. Mục tiêu là giảm technical debt, rút ngắn thời gian onboard cho người mới và dễ tạo build sạch khi prototype chuyển lên giai đoạn development.

Bài viết nhấn mạnh thực hành cụ thể: cấu trúc thư mục mẫu, ví dụ assembly definition (asmdef), một số script kiểm tra tự động (dùng AssetDatabase) để phát hiện vi phạm, và các lỗi thường gặp. Những nội dung nền tảng về cách Unity hoạt động được trích dẫn từ tài liệu chính thức của Unity khi cần [1][2][3][4].

Tại sao nên tổ chức ngay từ prototype?

Nhiều indie team coi prototype là "chỉ demo", do đó thường ép tất cả tài sản vào một thư mục và để scripts nằm lẫn lộn. Khi prototype phát triển thành sản phẩm, việc refactor tốn thời gian hơn nhiều so với thiết kế ranh giới từ đầu.

Lợi ích khi thiết kế sạch sớm:

• Giảm thời gian debug khi gặp lỗi liên quan đến editor code vô tình chạy trong build.

• Giảm rebuild time do assembly boundaries hợp lý (nhưng cũng cần cân nhắc số lượng asmdef) [3].

• Dễ viết tests và chạy CI (unit/Editor tests) nhờ tách assemblies theo chức năng [4].

• Quản lý tài sản rõ ràng, dễ nhìn và dễ tìm kiếm nhờ quy tắc đặt tên và cấu trúc thư mục có hệ thống [1][2].

Các khuyến nghị trong bài này dựa trên nguyên tắc tối thiểu hóa coupling, phân tách trách nhiệm và đảm bảo observable rule-set để mọi thành viên trong team dễ tuân theo.

Nguyên tắc chung

Trước khi vào chi tiết, đây là các nguyên tắc ngắn gọn áp dụng xuyên suốt:

1. Tách rõ runtime / editor / tests. Editor-only code phải biến mất khỏi runtime assemblies; tests phải ở assemblies riêng có mục đích rõ ràng [3][4].

2. Giữ số lượng thư mục cấp cao cố định trong Assets để dễ điều hướng (ví dụ: Assets/Project, Assets/ThirdParty, Assets/Packages, Assets/Scenes).

3. Dùng Assembly Definition (asmdef) để chia "boundaries" hợp lý — theo tính năng (feature) hơn là theo loại tài nguyên.

4. Hạn chế thư mục Resources; nếu cần asset được load động, ưu tiên serialized references hoặc hệ thống tải tách biệt.

5. Đặt tên nhất quán cho Scene/Prefab/Script/Component; mỗi loại có một quy ước cụ thể.

6. Kiểm tra tự động: viết một "sanity check" scene hoặc editor validation chạy trước commit/CI để phát hiện vi phạm.

Kiến trúc thư mục mẫu

Dưới đây là một cấu trúc thư mục đề xuất cho prototype nhỏ (1–4 devs). Mục tiêu: giữ mọi thứ đơn giản nhưng có ranh giới rõ ràng.

• Assets/

  • Project/

    • Runtime/

      • Core/

      • Gameplay/

      • UI/

      • Systems/

      • Data/ (ScriptableObjects, config, static data)

      • Prefabs/

      • Scenes/

    • Editor/

      • Tools/

      • Inspectors/

    • Tests/

      • EditorTests/

      • PlayModeTests/

  • Packages/ (local packages nếu có)

  • ThirdParty/

Giải thích ngắn:

• Project/Runtime: mã và tài nguyên dùng trong runtime. Chia theo tính năng (Core, Gameplay, UI).

• Project/Editor: code chỉ chạy trên Editor (custom inspectors, editor tools). Không nên có code này nằm chung với Runtime.

• Project/Tests: test assemblies tách biệt: EditorTests cho test phụ thuộc UnityEditor, PlayModeTests cho test chạy trong Play Mode.

• ThirdParty: các plugin bên ngoài, mỗi plugin một thư mục.

Bảng minh họa nội dung mỗi thư mục:

[IMAGE_02] Unity Project window/Asset Database chính thức, minh họa cách quan sát và phân loại asset trong project; không phải ảnh chụp project nội bộ. | Alt: Unity Project window minh họa việc quản lý asset trong Asset Database. | Media ID: cmsyg8vof09pk12yg18lfao72 | URL: /uploads/2026/08/18/10993d1a-60e6-4925-b478-edb026190582.webp | Nguồn: Unity Manual, tài liệu Asset Database; attribution được giữ trong metadata.

Lưu ý về số lượng thư mục: không cần quá nhỏ gọn, nhưng cũng tránh "mỗi file một folder". Giữ cân bằng theo nguyên tắc "1 level deep enough for quick scan".

Assembly Definition (asmdef) — thiết lập ranh giới

Assembly definitions cho phép bạn tách mã thành nhiều assembly, giúp giảm thời gian biên dịch và tạo ranh giới phụ thuộc rõ ràng. Tài liệu chính thức mô tả cách hoạt động của asmdef và cách thêm file assembly definition [3].

Quy tắc thực hành khi tạo asmdef:

• Tạo asmdef cho mỗi module/feature chính, ví dụ: Project.Runtime.Core.asmdef, Project.Runtime.Gameplay.asmdef, Project.Editor.Tools.asmdef, Project.Tests.Editor.asmdef.

• Editor asmdef: bật tùy chọn "Editor" (một flag trong asmdef) để chỉ biên dịch với UnityEditor present.

• Tests: tạo asmdef riêng với "testable" flags nếu cần; follow Unity Test Framework guidance [4].

• Không tạo quá nhiều asmdef nhỏ lẻ (mỗi script 1 asmdef), điều này gây overhead. Tốt nhất chia theo feature có ý nghĩa.

Ví dụ cấu trúc asmdef (JSON cơ bản):

{
  "name": "Project.Runtime.Core",
  "references": [],
  "includePlatforms": [],
  "excludePlatforms": [],
  "allowUnsafeCode": false,
  "overrideReferences": false,
  "precompiledReferences": [],
  "autoReferenced": true,
  "defineConstraints": [],
  "versionDefines": [],
  "noEngineReferences": false
}

Với Editor assembly:

{
  "name": "Project.Editor.Tools",
  "references": [],
  "includePlatforms": [],
  "excludePlatforms": [],
  "allowUnsafeCode": false,
  "overrideReferences": false,
  "precompiledReferences": [],
  "autoReferenced": false,
  "defineConstraints": [],
  "versionDefines": [],
  "noEngineReferences": false,
  "optionalUnityReferences": [],
  "isTestAssembly": false
}

Để tạo asmdef đúng cách, hãy tham khảo hướng dẫn chính thức của Unity về Script Compilation and Assembly Definition Files [3].

[IMAGE_03] Unity Manual minh họa nội dung và cấu hình Assembly Definition, phù hợp trực tiếp với phần tạo ranh giới runtime/editor/tests. | Alt: Unity Manual minh họa file Assembly Definition và các tham số assembly. | Media ID: cmsygf9bu09r812ygz0nnhjk5 | URL: /uploads/2026/08/18/6ed9f064-3251-49ce-b1c3-def64083c09d.webp | Nguồn: Unity Manual, Assembly Definition Files; attribution được giữ trong metadata.

Ranh giới runtime vs editor vs tests

• Runtime assembly: chứa mã không tham chiếu UnityEditor. Dùng trong build.

• Editor assembly: chứa mã chỉ chạy trong Editor (UnityEditor namespace). Đặt autoReferenced=false và đánh dấu là editor assembly (thông qua file asmdef hoặc đặt trong thư mục Editor) để không bị đóng gói vào build.

• Test assembly: asmdef có isTestAssembly=true nếu muốn Test Runner nhận diện; cần tham khảo Unity Test Framework [4].

Lưu ý: một số người dùng vẫn đặt Editor code vào thư mục tên "Editor" vì Unity có quy ước tự động không biên dịch những script trong thư mục Editor vào runtime. Tuy nhiên, dùng asmdef cho Editor assemblies giúp kiểm soát phụ thuộc tốt hơn [3].

Quy tắc đặt tên

Quy tắc đặt tên nhất quán giúp tìm kiếm và đọc mã nhanh. Dưới đây là các qui tắc đề xuất — tùy chỉnh cho team bạn nhưng phải được ghi lại và enforced.

Scenes:

• Tiền tố theo scope: MainMenu_Main.unity, Gameplay_Level_01.unity, Debug_Scene_Sanity.unity

• Sử dụng PascalCase cho từ và dấu gạch dưới để phân tách phần.

Prefabs:

• Sử dụng dạng Kebab cho loại + tên + variant: Enemy-Zombie-Fast.prefab, UI-Button-Primary.prefab.

• Đặt tất cả Prefab chung vào thư mục Prefabs theo feature (ví dụ: Runtime/Prefabs/Enemies).

Scripts:

• Class name = filename (bắt buộc trong Unity). Dùng PascalCase: PlayerController.cs, HealthSystem.cs.

• Components: tên kết thúc bằng "Controller"/"System"/"View" tùy loại. Ví dụ GameStateController, InventorySystem, HUDView.

• For ScriptableObjects: Suffix bằng "SO" hoặc "Data": WeaponDataSO.cs, LevelConfigSO.cs.

GameObjects inside Prefabs/Scenes:

• Root GameObject tên rõ ràng, không dùng default "GameObject" — ví dụ "Player_Root", "Enemy_Body".

• Child naming: ActionType_Target (e.g., "Gun_Muzzle", "Body_HitBox").

Assets (textures, audio):

• Texture: tex__ (tex_PlayerIcon_64)

• Audio: sfx/_, music/

Ví dụ bảng tóm tắt:

[IMAGE_04] Unity Hierarchy window chính thức minh họa scene và các GameObject trong quan hệ tổ chức, dùng cho quy tắc đặt tên root/child. | Alt: Unity Hierarchy window hiển thị scene và các GameObject. | Media ID: cmsyh2vxv09yl12yggn1um6o6 | URL: /uploads/2026/08/18/d8715370-2a7e-47f9-b322-94733848205c.webp | Nguồn: Unity Manual, https://docs.unity3d.com/Manual/Hierarchy.html; attribution được giữ trong metadata.

Quy tắc này giúp cho việc tìm kiếm qua Project window hoặc bằng script (AssetDatabase) trở nên dễ dàng.

Hạn chế Resources và các phương án thay thế

Unity's Resources folder cho phép load asset bằng Resources.Load ở runtime nhưng dễ bị lạm dụng: mọi asset trong thư mục Resources đều được đóng gói vào build, gây tăng kích thước và khó track dependency.

Khuyến nghị:

• Tránh sử dụng Resources cho assets lớn hoặc nhiều. Dùng Resources chỉ khi không có cách nào khác (ví dụ runtime loading dựa trên string không chịu được referencing).

• Thay thế:

  • Serialized references: drag & drop trực tiếp vào fields trong Inspector (an toàn, explicit).

  • ScriptableObjects làm config và registry cho prefab references.

  • Asset bundles hoặc hệ thống Addressables (nếu bạn dùng) cho tải động — nếu dùng Addressables, follow docs riêng.

• Nếu phải dùng Resources, có một cấu trúc: một folder Resources/Allow/ và một file README giải thích lý do.

Cách kiểm tra bằng code: tìm tất cả các prefab/scene có đường dẫn chứa "/Resources/". Dùng AssetDatabase để tìm kiếm — API được mô tả trong tài liệu [2].

Ví dụ code để tìm assets trong Resources:

using UnityEditor;
using UnityEngine;

public static class ResourcesAudit
{
    [MenuItem("Tools/Project Sanity/Find Resources Assets")]
    public static void FindResourcesAssets()
    {
        string[] guids = AssetDatabase.FindAssets("t:Prefab t:Scene t:ScriptableObject");
        foreach (string guid in guids)
        {
            string path = AssetDatabase.GUIDToAssetPath(guid);
            if (path.Contains("/Resources/"))
            {
                Debug.LogWarning($"Resource asset found: {path}");
            }
        }
    }
}

Chạy script này trong Editor để phát hiện vi phạm. Tham khảo API AssetDatabase trong tài liệu Unity [2].

[IMAGE_05] Unity Project window reference chính thức, dùng để minh họa việc duy trì cấu trúc thư mục dễ quét khi kiểm tra Resources và asset dependency. | Alt: Unity Project window reference với các thư mục và asset được hiển thị trong Editor. | Media ID: cmsygh0v509tc12yg31x9frtn | URL: /uploads/2026/08/18/78bde05d-99c8-42c7-96cd-4270a84607af.webp | Nguồn: Unity Manual, tài liệu Project window; attribution được giữ trong metadata.

Viết script kiểm tra "sanity" cho prototype

Một bước quan trọng là tự động hóa kiểm tra cơ bản mỗi khi commit hoặc chạy CI. Dưới đây là một ví dụ Editor script đơn giản thực hiện các kiểm tra:

• Phát hiện scripts có "using UnityEditor" nằm trong Runtime assemblies.

• Tìm assets ở thư mục Resources.

• Kiểm tra presence của asmdef ở folder Runtime (bắt buộc cho team này).

Ví dụ:

using UnityEditor;
using UnityEngine;
using System.Linq;
using System.IO;

public static class ProjectSanityCheck
{
    [MenuItem("Tools/Project Sanity/Run Sanity Check")]
    public static void Run()
    {
        Debug.Log("Running Project Sanity Check...");

        // 1) Find scripts referencing UnityEditor in Runtime folder
        var scriptGuids = AssetDatabase.FindAssets("t:MonoScript", new[] {"Assets/Project/Runtime"});
        foreach (var guid in scriptGuids)
        {
            var path = AssetDatabase.GUIDToAssetPath(guid);
            var text = File.ReadAllText(path);
            if (text.Contains("UnityEditor"))
            {
                Debug.LogError($"Editor API referenced in runtime script: {path}");
            }
        }

        // 2) Find assets in Resources
        var resourceGuids = AssetDatabase.FindAssets("", new[] {"Assets"});
        foreach (var g in resourceGuids)
        {
            var p = AssetDatabase.GUIDToAssetPath(g);
            if (p.Contains("/Resources/"))
            {
                Debug.LogWarning($"Resource found: {p}");
            }
        }

        // 3) Ensure asmdef exists in each top-level Runtime subfolder
        var runtimeFolders = Directory.GetDirectories("Assets/Project/Runtime");
        foreach (var folder in runtimeFolders)
        {
            var asmdefFiles = Directory.GetFiles(folder, "*.asmdef", SearchOption.TopDirectoryOnly);
            if (asmdefFiles.Length == 0)
            {
                Debug.LogWarning($"No asmdef in {folder}. Consider adding assembly definition.");
            }
        }

        Debug.Log("Sanity Check complete.");
    }
}

Bạn có thể mở rộng checks: xác thực naming convention, kích thước texture, tập kiểm tra prefab root naming, v.v. Các API này dùng AssetDatabase và hệ thống file; docs AssetDatabase cung cấp chi tiết hơn [2].

[IMAGE_06] Unity Package Manager chính thức, đặt cạnh phần audit để nhắc team phân biệt package/third-party dependency với tài nguyên trong Resources. | Alt: Unity Package Manager hiển thị các package của project. | Media ID: cmsygfo6l09rh12yggf9k9spp | URL: /uploads/2026/08/18/447e6c69-796c-44a9-8c49-4efb52332986.webp | Nguồn: Unity Manual, Package Manager; attribution được giữ trong metadata.

Tests — tách assembly cho test và ví dụ test

Unity Test Framework hỗ trợ viết Editor tests và Play Mode tests; bạn nên tách chúng vào assemblies riêng. Tham khảo hướng dẫn chính thức về Editor tests tại docs Unity [4].

Ví dụ một Editor test đơn giản dùng NUnit:

using NUnit.Framework;
using UnityEditor;
using UnityEngine;

public class ResourcesTests
{
    [Test]
    public void NoLargeResourcesFolder()
    {
        string[] guids = AssetDatabase.FindAssets("", new[] { "Assets/Project/Runtime" });
        foreach (var guid in guids)
        {
            string path = AssetDatabase.GUIDToAssetPath(guid);
            if (path.Contains("/Resources/"))
            {
                Assert.Fail($"Resources usage detected: {path}. Consider moving or justify it.");
            }
        }
    }
}

Đặt test này trong thư mục Assets/Project/Tests/EditorTests và đảm bảo asmdef của thư mục có isTestAssembly=true hoặc tham khảo Unity Test Runner để chạy [4].

[IMAGE_07] Unity Test Runner chính thức hiển thị workflow chạy test, phù hợp với phần EditorTests và PlayModeTests của prototype. | Alt: Unity Test Runner hiển thị giao diện chạy và kiểm tra test. | Media ID: cmsyg9zwj09pw12yglacsm6yj | URL: /uploads/2026/08/18/1ea54ee1-93b9-4f71-b721-070c7525a007.webp | Nguồn: Unity Test Framework documentation; attribution được giữ trong metadata.

Ví dụ scene mẫu để kiểm tra quy tắc

Tạo một scene kiểm tra tính "sạch" để dev có thể chạy local:

• Scene name: Debug_Scene_Sanity.unity

• Chứa một GameObject "SanityChecker" với component SanityChecker.cs (MonoBehaviour) có OnValidate hoặc một Button để gọi sanity checks.

• SanityChecker gọi các checks (tương tự script ở trên) và hiển thị kết quả trong UI nhỏ (Editor-only).

Sample SanityChecker (đặt trong Editor/ nếu dùng Editor-only API; nếu muốn runtime, chỉ dùng API safe):

#if UNITY_EDITOR
using UnityEditor;
using UnityEngine;

[ExecuteInEditMode]
public class SanityChecker : MonoBehaviour
{
    [ContextMenu("Run Sanity Check")]
    public void RunCheck()
    {
        ProjectSanityCheck.Run();
    }
}
#endif

Scene này giúp dev chạy quick-check trước commit và đảm bảo team tuân thủ quy tắc.

[IMAGE_08] Unity Hierarchy window chính thức minh họa quan hệ parent-child giữa các GameObject, phù hợp với phần tổ chức Debug_Scene_Sanity và cấu trúc scene. | Alt: Unity Hierarchy window minh họa quan hệ parent-child giữa các GameObject. | Media ID: cmsyh399i09z612ygxhshi1tr | URL: /uploads/2026/08/18/f4fe37ed-7eba-4fb5-8b33-2c24205b750d.webp | Nguồn: Unity Manual, https://docs.unity3d.com/Manual/Hierarchy.html; attribution được giữ trong metadata.

Lỗi thường gặp và cách khắc phục

1. Editor code bị đóng gói vào build

   • Triệu chứng: Build runtime crash liên quan đến UnityEditor namespace.

   • Nguyên nhân: Script có "using UnityEditor" nằm trong Runtime assembly hoặc ngoài thư mục Editor.

   • Khắc phục: Di chuyển script vào thư mục Editor hoặc vào asmdef editor-only. Dùng ProjectSanityCheck để phát hiện [3][2].

2. Tập tin Resources quá lớn

   • Triệu chứng: Build size lớn, assets vô tình được đóng gói.

   • Nguyên nhân: Tất cả asset trong thư mục Resources đều bị include.

   • Khắc phục: Dời asset lớn ra khỏi Resources, dùng Serialized references hoặc hệ thống tải động.

3. Quá nhiều asmdef nhỏ lẻ

   • Triệu chứng: Tăng ít nhưng đáng kể độ phức tạp cấu hình; build và manage references khó.

   • Nguyên nhân: Mỗi script được đóng gói thành asmdef.

   • Khắc phục: Gộp asmdef theo feature/module.

4. Tests phụ thuộc UnityEditor khi cần chạy PlayMode

   • Triệu chứng: Tests fail trên CI hoặc bị bỏ qua.

   • Nguyên nhân: Test type sai assemblies.

   • Khắc phục: Tách EditorTests và PlayModeTests, đảm bảo isTestAssembly thiết lập phù hợp [4].

5. Tên GameObject/Prefab không nhất quán

   • Triệu chứng: Khó tìm prefab khi debug, search không chính xác.

   • Nguyên nhân: Không có naming convention hoặc không tuân thủ.

   • Khắc phục: Áp dụng quy tắc đặt tên và dùng script kiểm tra.

[IMAGE_09] Unity Test Framework workflow chính thức, dùng để minh họa bước chạy lại test sau khi sửa lỗi và trước khi merge; không phải output của project nội bộ. | Alt: Unity Test Framework minh họa workflow kiểm thử trong Unity Editor. | Media ID: cmsygg36e09sy12yg9pbq4psu | URL: /uploads/2026/08/18/019c28b6-9288-4ef7-8ecd-3051fad5d7bc.webp | Nguồn: Unity Test Framework documentation; attribution được giữ trong metadata.

Áp dụng cho team nhỏ — workflow thực hành

Gợi ý workflow khi bắt đầu prototype:

1. Tạo repo với template thư mục như đề xuất.

2. Tạo asmdef cho từng folder runtime lớn và editor.

3. Thiết lập pre-commit hook gọi Unity -batchmode hoặc script chạy ProjectSanityCheck (Editor script) để fail pre-commit nếu vi phạm nghiêm trọng.

4. Đặt scene Debug_Scene_Sanity làm default scene để dev có thể test.

5. Viết vài Editor tests / Editor runners để tự động hóa kiểm tra.

6. Ghi rõ quy tắc đặt tên trong CONTRIBUTING.md của repo.

Lưu ý: các bước cần điều chỉnh theo toolchain CI/CD của bạn. Tài liệu Unity Manual cung cấp nhiều hướng dẫn chung về AssetDatabase, build và project organization [1][2][3][4].

Kết luận

Thiết kế một Unity prototype "sạch" ngay từ ngày đầu không đồng nghĩa tạo một hệ thống quá phức tạp; mà là đặt ra những ranh giới rõ ràng (runtime/editor/tests), quy tắc đặt tên nhất quán, và tự động hóa kiểm tra cơ bản để ngăn technical debt tích tụ. Dùng asmdef một cách hợp lý giúp kiểm soát phụ thuộc và giảm compile time; hạn chế dùng Resources giúp giảm kích thước build và duy trì dependency explicit. Hãy bắt đầu với một cấu trúc thư mục đơn giản, áp dụng các quy tắc tên và bổ sung sanity checks tự động — bạn sẽ tiết kiệm nhiều thời gian khi prototype tiến sang giai đoạn phát triển tiếp theo.

Checklist thực hành

• Tạo cấu trúc thư mục: Assets/Project/{Runtime,Editor,Tests}

• Tạo ít nhất một asmdef cho mỗi module runtime lớn

• Đặt code Editor vào Editor folder hoặc asmdef editor-only

• Không sử dụng "using UnityEditor" trong runtime scripts

• Giới hạn / loại bỏ thư mục Resources; tạo README nếu cần

• Tạo Debug_Scene_Sanity với SanityChecker component

• Thêm ProjectSanityCheck menu và chạy locally trước commit

• Tách EditorTests và PlayModeTests với asmdef phù hợp

• Ghi quy ước đặt tên vào CONTRIBUTING.md

• Thêm pre-commit hook gọi sanity checks (nếu có CI)

References

[1] Unity Manual — Main manual: https://docs.unity3d.com/Manual/
[2] Unity Manual — AssetDatabase: https://docs.unity3d.com/Manual/AssetDatabase.html
[3] Unity Manual — Script Compilation & Assembly Definition Files: https://docs.unity3d.com/Manual/ScriptCompilationAssemblyDefinitionFiles.html
[4] Unity Manual — Testing in the Editor: https://docs.unity3d.com/Manual/testing-editortests.html