Unity ECS Component Generator

Critical Instructions

• •Interpret Intent: Xác định chính xác loại component cần sinh (data, shared, buffer, tag, cleanup, enableable). Hỏi lại nếu không rõ.
• •Project Convention: Luôn tuân thủ kiến trúc trong AI_INSTRUCTIONS.md và README.md trước khi sinh code.
• •Output Path: Đặt file vào Assets/Scripts/Core/Data/ trừ khi user chỉ định khác.

Core Principles

• •Unmanaged Only: Tất cả component PHẢI là unmanaged struct. KHÔNG dùng class, string, managed array.
• •Burst Compatible: Chỉ dùng blittable types (byte, int, float, bool, int3, float3, quaternion, FixedString64Bytes).
• •Minimal Data: Mỗi component chỉ chứa dữ liệu cần thiết. Logic thuộc về System.
• •Naming: Tên component phải rõ ràng, diễn tả dữ liệu, hậu tố phù hợp (vd: VoxelData, ChunkCoordinate, TemperatureTag).

Component Types Reference

1. IComponentData (Standard Data)

Dùng cho dữ liệu gắn vào từng Entity.

using Unity.Entities;
using Unity.Mathematics;

/// <summary>
/// [Mô tả ngắn gọn component chứa gì, thuộc hệ thống nào]
/// </summary>
public struct ExampleComponent : IComponentData
{
    public float Value;
    public int3 Coordinate;
}

2. Tag Component (Empty IComponentData)

Dùng để đánh dấu, lọc Entity bằng query mà không chứa data.

/// <summary>
/// Đánh dấu Entity cần được xử lý bởi [SystemName].
/// </summary>
public struct NeedsProcessingTag : IComponentData { }

3. ISharedComponentData

Dùng khi nhiều Entity chia sẻ cùng giá trị (vd: MaterialID, ChunkIndex) để tối ưu chunk grouping.

/// <summary>
/// Nhóm Entity theo [tiêu chí]. Thay đổi giá trị gây structural change.
/// </summary>
public struct MaterialGroup : ISharedComponentData
{
    public int MaterialID;
}

4. IBufferElementData (Dynamic Buffer)

Dùng cho danh sách có kích thước thay đổi theo thời gian.

/// <summary>
/// Buffer chứa [dữ liệu gì] cho mỗi Entity.
/// </summary>
[InternalBufferCapacity(8)]
public struct NeighborElement : IBufferElementData
{
    public Entity Value;
}

5. IEnableableComponent

Component có thể bật/tắt mà không gây structural change.

/// <summary>
/// Khi enabled, Entity sẽ được xử lý bởi [SystemName].
/// </summary>
public struct ActiveFlag : IComponentData, IEnableableComponent
{
    public float TimeRemaining;
}

6. ICleanupComponentData

Tự động gắn lại sau khi Entity bị destroy, dùng cho cleanup logic.

/// <summary>
/// Cleanup marker để giải phóng [tài nguyên gì] khi Entity bị hủy.
/// </summary>
public struct CleanupAfterDestroy : ICleanupComponentData
{
    public int ResourceHandle;
}

Project-Specific Patterns (VisualWorld)

VoxelData (Core Data Struct)

/// <summary>
/// Dữ liệu lõi của một voxel trong GlobalVoxelMap.
/// Kích thước: 4 bytes. Được lưu trong UnsafeList<VoxelData> theo chunk.
/// </summary>
public struct VoxelData
{
    public byte MaterialID;   // ID vật liệu (tối đa 255 loại)
    public byte State;        // Phase: 0=Air, 1=Solid, 2=Liquid, 3=Gas
    public byte Temperature;  // Normalized 0-255 -> map sang range thực tế
    public byte Stress;       // Tải trọng tích lũy 0-255
}

ChunkCoordinate (Chunk Identity)

/// <summary>
/// Tọa độ chunk trong không gian thế giới. Dùng cho Chunk Entity.
/// </summary>
public struct ChunkCoordinate : IComponentData
{
    public int3 Value;
}

DirtyChunkTag (Rebuild Trigger)

/// <summary>
/// Đánh dấu chunk cần rebuild mesh trong frame tiếp theo.
/// </summary>
public struct DirtyChunkTag : IComponentData { }

Generation Workflow

1. •Xác định loại component → Data / Tag / Shared / Buffer / Enableable / Cleanup
2. •Xác định fields → Chỉ blittable types, tối thiểu hóa kích thước
3. •Viết XML doc → Mô tả component thuộc system nào, mục đích gì
4. •Đặt namespace → VisualWorld.Core.Data hoặc namespace phù hợp module
5. •Đặt file → Assets/Scripts/Core/Data/{ComponentName}.cs

Validation Checklist

• • Struct, không phải class
• • Implement đúng interface (IComponentData, ISharedComponentData, v.v.)
• • Không có managed types (string, array, List, class reference)
• • Kích thước struct hợp lý (< 128 bytes cho IComponentData)
• • Có XML documentation comment
• • Tên file khớp tên struct