Memory Layout Analyzer

ECSのChunkメモリレイアウトをASCII図で可視化し、最適化提案を行います。

使用方法

/memory-layout-analyzer [component_names...]

•引数なし: 主要なArchetypeを分析
•コンポーネント名指定: 特定の組み合わせを分析

例:

•/memory-layout-analyzer → 全Archetype概要
•/memory-layout-analyzer LocalTransform VelocityData → 特定の組み合わせ
•/memory-layout-analyzer TransformData → 単一コンポーネント

分析対象

1. コンポーネントサイズとアライメント

ソースコードから抽出:

•sizeof(T) と alignof(T)
•alignas() 指定
•パディング

2. Chunkメモリマップ

16KB Chunk内のSoA（Structure of Arrays）レイアウト:

code

┌────────────────────────────────────────────────────────────────┐
│                        16KB CHUNK                               │
├────────────────────────────────────────────────────────────────┤
│ ACTOR ARRAY (capacity × 4 bytes)                                │
│ [Actor0][Actor1][Actor2]...[ActorN]                            │
├────────────────────────────────────────────────────────────────┤
│ PADDING (64-byte alignment)                                     │
├────────────────────────────────────────────────────────────────┤
│ COMPONENT ARRAY: LocalTransform (capacity × 48 bytes)          │
│ [LT0][LT1][LT2]...[LTN]                                        │
├────────────────────────────────────────────────────────────────┤
│ COMPONENT ARRAY: VelocityData (capacity × 16 bytes)            │
│ [V0][V1][V2]...[VN]                                            │
├────────────────────────────────────────────────────────────────┤
│ UNUSED SPACE                                                    │
└────────────────────────────────────────────────────────────────┘

3. キャッシュライン境界

64バイト境界を表示:

code

Offset    Content              Cache Line
──────────────────────────────────────────
0x0000    Actor[0-15]          ├─ CL 0
0x0040    Actor[16-31]         ├─ CL 1
0x0080    Padding              ├─ CL 2
0x00C0    LocalTransform[0]    ├─ CL 3  ← コンポーネント開始
0x0100    LocalTransform[1]    ├─ CL 4
...

実行手順

1. コンポーネント情報を収集

source/engine/ecs/components/ からコンポーネント定義を読み取り:

cpp

struct alignas(16) VelocityData : public IComponentData {
    Vector3 value;   // 12 bytes
    float _pad0;     // 4 bytes
};  // Total: 16 bytes, align: 16

2. Archetypeレイアウトを計算

code

1 Actor あたり:
  - Actor: 4 bytes
  - LocalTransform: 48 bytes (alignas(16))
  - VelocityData: 16 bytes (alignas(16))
  = 68 bytes/entity

Chunk容量: floor(16384 / 68) = 240 entities

3. ASCII図を生成

詳細なメモリマップを出力。

レポートフォーマット

code

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 CHUNK MEMORY LAYOUT ANALYSIS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🏗️ Archetype: LocalTransform + VelocityData

📐 COMPONENT SIZES
───────────────────────────────────────────────────

┌────────────────────┬────────┬───────┬──────────┐
│ Component          │ Size   │ Align │ Padding  │
├────────────────────┼────────┼───────┼──────────┤
│ Actor              │ 4B     │ 4     │ 0B       │
│ LocalTransform     │ 48B    │ 16    │ 0B       │
│ VelocityData       │ 16B    │ 16    │ 0B       │
└────────────────────┴────────┴───────┴──────────┘

Total per entity: 68 bytes

📦 CHUNK LAYOUT (16KB = 16,384 bytes)
───────────────────────────────────────────────────

Capacity: 240 entities

Offset      Size        Content
──────────────────────────────────────────────────
0x0000      960B        Actor[0..239]
0x03C0      64B         Padding (64B align)
0x0400      11520B      LocalTransform[0..239]
0x3100      3840B       VelocityData[0..239]
0x4000      ---         End of Chunk

Used: 16,384B / 16,384B (100.0%)

📊 CACHE LINE ANALYSIS (64B lines)
───────────────────────────────────────────────────

Actor array:
  └─ 15 cache lines (960B), 16 Actors/line

LocalTransform array:
  └─ 180 cache lines (11,520B), 1.33 transforms/line
  ⚠️ Cross-boundary access: 33% of entities

VelocityData array:
  └─ 60 cache lines (3,840B), 4 velocities/line
  ✓ Aligned access: 100%

💡 OPTIMIZATION SUGGESTIONS
───────────────────────────────────────────────────

1. LocalTransform (48B) は64Bキャッシュラインに収まらない
   → 2/3のアクセスでキャッシュラインをまたぐ
   → Position(16B) + Rotation(16B) + Scale(16B) に分割検討

2. VelocityData は4要素/キャッシュラインで効率的 ✓

3. 推奨: 高頻度アクセスコンポーネントはサイズを
   16B, 32B, 64B のいずれかに揃える

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

コンポーネントサイズ一覧

主要コンポーネント（参考）:

Component	Size	Align	Fields
Actor	4B	4	index(20bit) + gen(12bit)
LocalTransform	48B	16	position(16) + rotation(16) + scale(16)
VelocityData	16B	16	value(12) + pad(4)
SpriteData	64B	16	texture + uv + color + flags
MeshData	32B	8	mesh + material handles

最適化ガイドライン

キャッシュ効率

サイズ	要素/CL	効率
16B	4	★★★★★
32B	2	★★★★☆
48B	1.33	★★★☆☆
64B	1	★★★★☆

Chunk充填率目標

•95%以上: 優秀
•80-95%: 良好
•80%未満: 改善推奨（コンポーネント分割を検討）

注意事項

•SoAレイアウト: 各コンポーネント型は連続配置
•Actor配列先頭: Chunk先頭にActor IDが並ぶ
•アライメントパディング: 64B境界にアライン