2nd/10_Wiki/Topic_Business/Skybound/Skybound_Enemy_Orientation_Fix.md

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-skybound-enemy-orientation-fix	Skybound Enemy Orientation Fix	10_Wiki/Topics	verified	self	Enemy Facing Bug Sprite Flip Fix Orientation Update Loop	none	A	0.9	applied	skybound combat-ai sprite orientation bugfix		2026-05-10	pending	language framework typescript skybound-engine

Skybound Enemy Orientation Fix

매 한 줄

"매 enemy facing 의 source-of-truth 는 velocity, not last-input". Skybound 의 enemy 가 stationary 시 wrong direction face 하던 bug — orientation 을 velocity-derived 로 unify 하고, idle fallback 으로 player-facing 적용. 매 2D action game 의 standard fix.

매 핵심

매 문제

• Enemy 가 path target 에 도달 후 멈추면 last-known facing 유지.
• Player 가 옆에 다가가도 그대로 → unrealistic + hitbox mismatch.
• Sprite flip 이 movement input 에만 react.

매 fix axes

• Velocity-driven facing: |vx| > epsilon 시 sign(vx) 로 flip.
• Idle fallback to player: |v| < eps 일 때 face nearest threat.
• Hysteresis: rapid flip 방지 (oscillation guard).
• Animation sync: orientation change 시 anim state machine 의 transition.

매 응용

1. Skybound enemy AI.
2. 2D platformer enemy facing.
3. Top-down shooter NPC orientation.

💻 패턴

Velocity-driven facing

const FACING_EPS = 0.05;
function updateFacing(enemy: Enemy, dt: number): void {
  if (Math.abs(enemy.velocity.x) > FACING_EPS) {
    enemy.facing = enemy.velocity.x > 0 ? "right" : "left";
    enemy.idleTime = 0;
    return;
  }
  enemy.idleTime += dt;
  if (enemy.idleTime > 0.2) {
    const player = enemy.world.player;
    enemy.facing = player.position.x >= enemy.position.x ? "right" : "left";
  }
}

Hysteresis guard (anti-flip)

const FLIP_HYSTERESIS_MS = 120;
function setFacing(enemy: Enemy, target: Facing, now: number): void {
  if (enemy.facing === target) return;
  if (now - enemy.lastFlipMs < FLIP_HYSTERESIS_MS) return;
  enemy.facing = target;
  enemy.lastFlipMs = now;
  enemy.sprite.flipX = target === "left";
}

Animation state sync

function syncAnimToFacing(enemy: Enemy): void {
  const dir = enemy.facing;
  const stateName = `${enemy.animState}_${dir}`;
  if (enemy.sprite.currentAnim !== stateName) {
    enemy.sprite.play(stateName, { preserveFrame: true });
  }
}

8-direction variant

type Dir8 = "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW";
function vecToDir8(v: Vec2): Dir8 {
  const angle = Math.atan2(v.y, v.x); // -π..π
  const idx = Math.round(((angle + Math.PI) / (Math.PI / 4))) % 8;
  return (["W", "SW", "S", "SE", "E", "NE", "N", "NW"] as Dir8[])[idx];
}

Hitbox mirror with facing

function getHitboxWorld(enemy: Enemy): Rect {
  const local = enemy.attackHitbox;
  const x = enemy.facing === "right"
    ? enemy.position.x + local.x
    : enemy.position.x - local.x - local.w;
  return { x, y: enemy.position.y + local.y, w: local.w, h: local.h };
}

Test: facing follows velocity

test("facing follows velocity sign", () => {
  const e = makeEnemy({ position: { x: 0, y: 0 } });
  e.velocity = { x: 2, y: 0 };
  updateFacing(e, 0.016);
  expect(e.facing).toBe("right");
  e.velocity = { x: -2, y: 0 };
  updateFacing(e, 0.016);
  expect(e.facing).toBe("left");
});

매 결정 기준

상황	Approach
Pure 2D side-scroller	velocity sign(vx) 만 사용
Top-down 4/8-dir	vecToDir8 with hysteresis
Stationary turret	always face nearest threat
Flying enemy	facing = velocity dir, decoupled from gravity

기본값: velocity-driven + idle fallback + hysteresis + anim sync.

🔗 Graph

• 응용: Skybound Knowledge Hub

🤖 LLM 활용

언제: 2D action game enemy facing bug, hitbox mirror, anim sync. 언제 X: 3D character (use root motion + IK), turn-based grid.

❌ 안티패턴

• Last-input facing: stationary 시 stale.
• No hysteresis: zigzag motion 에서 sprite flicker.
• Hitbox not mirroring: visual ↔ collision mismatch.
• Anim transition snap: facing change 시 frame reset → ugly.

🧪 검증 / 중복

• Verified (Skybound bugfix 2026-04 + 2D game dev standard practice).
• 신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — FULL spec rewrite with orientation patterns