refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조

에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-11 11:05:56 +09:00
parent 6549ead309
commit c24165b8bc
6193 changed files with 1717 additions and 31 deletions
@@ -0,0 +1,188 @@
+---
+id: wiki-2026-0508-stat-injection-and-visual-render
+title: Stat Injection and Visual Renderer Pipeline
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [Stat Injection Pipeline, Visual Renderer Pipeline]
+duplicate_of: none
+source_trust_level: B
+confidence_score: 0.8
+verification_status: applied
+tags: [game-engine, ecs, rendering-pipeline, data-flow]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: rust
+  framework: bevy
+---
+
+# Stat Injection and Visual Renderer Pipeline
+
+## 매 한 줄
+> **"매 simulation stats (HP, mana, status) → 매 visual layer (sprites, VFX, UI) 의 one-way injection pipeline"**. 매 game engine 의 ECS pattern + 매 render system. 매 simulation tick 의 authoritative state → 매 frame-rate-independent rendering. 2026 매 Bevy ECS, Unity DOTS, Unreal MASS 가 매 reference.
+
+## 매 핵심
+
+### 매 데이터 흐름
+1. **Simulation tick** (fixed 60 Hz): 매 stats mutation (Damage, Heal, StatusEffect).
+2. **Stat aggregation**: 매 base + buffs + equipment modifiers.
+3. **Injection layer**: 매 simulation stats → 매 visual components (HealthBar, SpriteTint, ParticleEmitter).
+4. **Render pipeline**: 매 cull → batch → draw call → GPU.
+5. **Frame interpolation**: 매 sim tick rate 와 매 render rate 의 mismatch 의 smooth.
+
+### 매 layers
+- **Authoritative**: simulation Components (Health, Mana, Position).
+- **Derived/Display**: Visual Components (DisplayHealth, FlashTimer, FloatingText).
+- **Renderer**: Sprite, Mesh, Material, Shader.
+- **Pipeline stages**: Update → Late Update → PostUpdate → Render.
+
+### 매 응용
+1. RPG combat — damage number 의 popup, sprite flash on hit.
+2. RTS — health bar, status icon, fog-of-war overlay.
+3. Action game — hit-stop, screen shake, VFX 의 trigger.
+
+## 💻 패턴
+
+### Bevy ECS (Rust 1.83) — stat → visual injection
+```rust
+use bevy::prelude::*;
+
+#[derive(Component)] struct Health { current: f32, max: f32 }
+#[derive(Component)] struct HealthBar; // visual marker
+#[derive(Component)] struct DamageFlash { timer: Timer }
+
+fn inject_health_to_bar(
+    actors: Query<&Health, Changed<Health>>,
+    mut bars: Query<(&Parent, &mut Sprite), With<HealthBar>>,
+) {
+    for (parent, mut sprite) in bars.iter_mut() {
+        if let Ok(h) = actors.get(parent.get()) {
+            let ratio = h.current / h.max;
+            sprite.custom_size = Some(Vec2::new(64.0 * ratio, 6.0));
+            sprite.color = Color::rgb(1.0 - ratio, ratio, 0.0);
+        }
+    }
+}
+```
+
+### Damage event → flash injection
+```rust
+#[derive(Event)] struct DamageEvent { target: Entity, amount: f32 }
+
+fn on_damage(
+    mut events: EventReader<DamageEvent>,
+    mut commands: Commands,
+    mut healths: Query<&mut Health>,
+) {
+    for ev in events.read() {
+        if let Ok(mut h) = healths.get_mut(ev.target) {
+            h.current -= ev.amount;
+            commands.entity(ev.target).insert(DamageFlash {
+                timer: Timer::from_seconds(0.15, TimerMode::Once),
+            });
+        }
+    }
+}
+
+fn tick_flash(
+    time: Res<Time>,
+    mut q: Query<(Entity, &mut DamageFlash, &mut Sprite)>,
+    mut commands: Commands,
+) {
+    for (e, mut f, mut s) in q.iter_mut() {
+        f.timer.tick(time.delta());
+        s.color = if f.timer.finished() { Color::WHITE } else { Color::RED };
+        if f.timer.finished() { commands.entity(e).remove::<DamageFlash>(); }
+    }
+}
+```
+
+### Frame interpolation (fixed sim, variable render)
+```rust
+#[derive(Component)] struct Transform2D { pos: Vec2 }
+#[derive(Component)] struct PrevPos(Vec2);
+
+fn interpolate_render(
+    fixed: Res<FixedTime>,
+    q: Query<(&Transform2D, &PrevPos, &mut Transform)>,
+) {
+    let alpha = fixed.accumulated().as_secs_f32() / fixed.timestep().as_secs_f32();
+    for (cur, prev, mut t) in q.iter_mut() {
+        let p = prev.0.lerp(cur.pos, alpha);
+        t.translation = p.extend(t.translation.z);
+    }
+}
+```
+
+### Render pipeline stages (Bevy schedule)
+```rust
+app.add_systems(FixedUpdate, (apply_damage, regen_mana))
+   .add_systems(Update, (inject_health_to_bar, tick_flash))
+   .add_systems(PostUpdate, (cull_offscreen, batch_sprites));
+```
+
+### Floating damage text
+```rust
+fn spawn_damage_text(mut commands: Commands, mut events: EventReader<DamageEvent>,
+                     transforms: Query<&Transform>) {
+    for ev in events.read() {
+        let tf = transforms.get(ev.target).unwrap();
+        commands.spawn((
+            Text2dBundle { text: Text::from_section(format!("{}", ev.amount as i32),
+                TextStyle { font_size: 24.0, color: Color::YELLOW, ..default() }),
+                transform: *tf, ..default() },
+            FloatingText { lifetime: Timer::from_seconds(1.0, TimerMode::Once), velocity: Vec2::Y * 50.0 },
+        ));
+    }
+}
+```
+
+### Modifier aggregation (base + buffs + equipment)
+```rust
+fn aggregate_attack(
+    mut q: Query<(&BaseStats, &Buffs, &Equipment, &mut DerivedAttack)>,
+) {
+    for (base, buffs, eq, mut atk) in q.iter_mut() {
+        let mut v = base.attack;
+        v += eq.iter().map(|i| i.attack_bonus).sum::<f32>();
+        v *= 1.0 + buffs.iter().map(|b| b.attack_mult).sum::<f32>();
+        atk.0 = v;
+    }
+}
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| Modern data-oriented engine | Bevy ECS / Unity DOTS / Unreal MASS |
+| OOP legacy engine | Component pattern + observer for stat→visual |
+| Multiplayer authoritative server | Server simulation, client interpolation |
+| Animation-heavy | Skeletal animation system separate from stats |
+
+**기본값**: ECS — sim Components → 매 system 의 derive Visual Components → renderer 의 read-only.
+
+## 🔗 Graph
+- 부모: [[Entity Component System]]
+- Adjacent: [[Bevy]] · [[Fixed Timestep]]
+
+## 🤖 LLM 활용
+**언제**: 매 game development, 매 simulation/render decoupling, 매 ECS pipeline 의 design.
+**언제 X**: 매 일반 web/backend, 매 simple tool — over-engineering.
+
+## ❌ 안티패턴
+- **Render reads sim mid-tick**: 매 tearing — 매 PostUpdate 의 inject 의 사용.
+- **Visual mutates simulation**: 매 one-way 의 violation — 매 determinism 의 lost (multiplayer fatal).
+- **Damage 의 main thread blocking VFX**: 매 frame drop. 매 event-driven, async.
+- **Per-frame allocation**: 매 GC stutter — 매 object pool, 매 ECS의 contiguous storage.
+
+## 🧪 검증 / 중복
+- Verified (Bevy 0.14 docs 2025; Unity DOTS docs; *Game Engine Architecture* Gregory 3rd ed).
+- 신뢰도 B (synthesis from multiple engine practices).
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — full ECS injection pipeline with Bevy patterns |