game-dev-rust-godot

Game Development: Rust + WASM / Godot 4.x

When to Use This vs Others

• Use this (game-dev-rust-godot) for end-to-end production workflow (assets→spec→tests→implementation) in Rust+WASM or Godot.
• Use game-design before coding when gameplay concept, loops, and feature priorities are still being shaped.
• Use godot when the task is engine-deep Godot implementation details rather than cross-stack production orchestration.

Dedicated workflow for HTML5 game production. Direct instruction from Master (2026-02-06): Use only Rust + WASM or Godot.

🚀 Tech Stack (Mandatory Compliance)

✅ Allowed Technologies

• Rust + WASM: Macroquad (recommended), Bevy
• Godot 4.x: HTML5 Export

❌ Prohibited Technologies

• JavaScript/TypeScript (all JS frameworks such as Phaser, PixiJS, Three.js)
• Unity WebGL
• Other web game engines

📋 Workflow Overview

1. 에셋 확보 (코딩 전 필수!)
   ↓
2. 에셋 기반 기획 구체화
   ↓
3. 메카닉 검증 (프로토타입)
   ↓
4. 테스트케이스 작성 (TDD)
   ↓
5. 구현 ↔ 기획 보완 (TC 100% PASS까지)
   ↓
6. QA (Playwright + 수동)
   ↓
7. 런칭 테스트
   ↓
8. 보고 (스크린샷 4장 + DoD 체크리스트)

🎨 Asset Acquisition (Phase 1 - Mandatory!)

⛔ Absolutely forbidden to start coding without assets

Asset Source Priority

1. NAS Game Madang (/Volumes/workspace/Asset Store-5.x/, 265 packages)
2. MiniPC Gemini AI generation (browser.proxy, node=MiniPC)
3. Free assets (kenney.nl CC0, opengameart.org, freesound.org)
4. MacBook MLX Z-Image-Turbo (nodes.run, node=MacBook Pro)
5. Blender 3D→2D rendering (MiniPC)

Mandatory Asset Checklist

□ 캐릭터/오브젝트 스프라이트
□ 배경 이미지/타일맵
□ UI 요소 (버튼, 아이콘, 패널)
□ BGM 최소 1곡 (mp3/ogg, 루프)
□ SFX 최소 3개 (클릭, 성공, 실패)
□ 에셋 라이선스 확인 (CC0/MIT/상용 허용)

License Policy (Public Games):

• ✅ Kenney.nl CC0, AI-generated, self-made
• ❌ Unity Asset Store (including free), assets that prohibit redistribution

🦀 Rust + WASM Implementation

Macroquad (recommended)

Project Creation (MiniPC):

cd $HOME/spritz/dynamic/games/<game-name>
cargo init

Cargo.toml:

[package]
name = "game-name"
version = "0.1.0"
edition = "2021"

[dependencies]
macroquad = "0.4"

[profile.release]
opt-level = "z"
lto = true

Basic Structure (src/main.rs):

use macroquad::prelude::*;

#[macroquad::main("Game Title")]
async fn main() {
    loop {
        clear_background(BLACK);
        
        // 게임 로직
        
        next_frame().await
    }
}

Build & Deploy:

# MiniPC에서
cargo build --release --target wasm32-unknown-unknown

# WASM 파일 복사
cp target/wasm32-unknown-unknown/release/<game-name>.wasm .

# index.html 생성 (Macroquad 자동 제공)

Detailed Guide: references/rust-macroquad.md reference

Bevy (Advanced)

Use only when a complex ECS structure is needed. Build time is long (7 min+) and WASM size is large (3.6MB+).

Detailed Guide: references/rust-bevy.md reference

🎮 Godot 4.x Implementation

Project Creation (MiniPC)

cd $HOME/godot4/projects
mkdir <game-name>
cd <game-name>

# project.godot 생성
godot4 --headless --path . --quit

HTML5 Export Settings

1. Add Export Preset:

   • Project → Export → Add... → Web
   • Export Path: build/web/index.html

2. Optimize Settings:

   • Texture Format: VRAM Compressed
   • Head Include: Custom HTML template (if needed)

Build & Deploy

# MiniPC에서
godot4 --headless --path . --export-release "Web"

# 결과물: build/web/ (index.html, *.wasm, *.pck)

Detailed Guide: references/godot-html5.md reference

✅ Writing Test Cases (Phase 4 - TDD)

Write TCs before implementation

TC Categories

Functional TC

TC-F001: 게임 시작 시 타이틀 화면 표시
TC-F002: 시작 버튼 클릭 시 게임 플레이 진입
TC-F003: [핵심 메카닉] 입력에 대한 올바른 반응
TC-F004: 점수/진행도 업데이트
TC-F005: 게임 오버 조건 충족 시 결과 화면 표시

UI/UX TC

TC-U001: 모바일 뷰포트 (390x844) 정상 표시
TC-U002: 가로 스크롤 없음
TC-U003: 터치 영역 최소 44x44px
TC-U004: safe-area 적용

Performance TC

TC-P001: 페이지 로드 5초 이내
TC-P002: JS 콘솔 에러 0개
TC-P003: 60fps 유지 (게임플레이 중)

TC Document Location: specs/games/<game>/test-cases.md

🔄 Implementation ↔ Planning Refinement Loop (Phase 5)

Repeat until TC 100% PASS:

구현 (TC 기반)
  ↓
TC 실행
  ↓
FAIL → 코드 수정 or 기획 조정
  ↓
재구현
  ↓
TC 재실행
  ↓
ALL PASS → Phase 6으로

Exit Conditions:

□ 모든 기능 TC PASS
□ 모든 UI/UX TC PASS
□ 모든 성능 TC PASS
□ DoD 체크리스트 전항목 충족

🧪 QA (Phase 6)

Automated Testing (MiniPC Playwright)

# MiniPC에서
cd $HOME/qa-automation
playwright test games/<game-name>.spec.ts

Mandatory Verification Items:

□ 페이지 로드 성공 (5초 내)
□ JS 콘솔 에러 0개
□ 시작 버튼 클릭 가능
□ 게임 플레이 가능 (5초 이상 생존)
□ 모바일 뷰포트 (390x844) 정상 표시

Manual Checklist

□ 전체 게임 루프 1회 완주
□ 에지 케이스 테스트
□ 사운드 재생 확인 (BGM + SFX)
□ 반응형 확인 (데스크톱 + 모바일)

Screenshot Capture (minimum 4)

□ 타이틀 화면
□ 게임플레이 (진행 중)
□ UI 요소 (메뉴, 설정 등)
□ 결과 화면 (게임오버/클리어)

📦 Deployment

Rust + WASM

# eastsea.monster/games/<game>/ 에 배포
- index.html
- <game>.wasm
- mq_js_bundle.js (Macroquad)
- assets/ (에셋 폴더)

Godot

# build/web/ 내용을 eastsea.monster/games/<game>/ 에 배포
- index.html
- <game>.wasm
- <game>.pck
- assets/ (에셋 폴더, 필요 시)

✅ Definition of Done

All must be satisfied to complete:

□ 실제 이미지 에셋 적용 (CSS 도형/emoji 금지)
□ 실제 오디오 에셋 적용 (oscillator 금지)
□ TC 100% PASS
□ Playwright 자동 테스트 통과
□ 스크린샷 4장 이상
□ 모바일 반응형 확인
□ 치명적 버그 0개
□ og.png 생성 (1200x630)
□ 런칭 테스트 통과 (실제 URL)

🎯 Game Grade Criteria

Grade	Criteria	Action
A	All DoD items satisfied, TC 100% PASS	Maintain & market
B	Game works, some assets lacking or TC not passed	Replace assets + supplement TC
C	Only code exists, no assets at all, TC not written	Restart from Phase 1
F	No index.html, empty directory, crash	Delete or remake

📚 Detailed Guide

• Rust Macroquad: references/rust-macroquad.md
• Rust Bevy: references/rust-bevy.md
• Godot HTML5: references/godot-html5.md
• Asset License: references/asset-licensing.md
• Performance Optimization: references/optimization.md

⚠️ Important Constraints

1. Tech Stack: Rust + WASM or Godot only
2. Assets first: Secure all assets before coding
3. TDD required: Implement after writing TCs
4. Mobile first: Implement responsive simultaneously
5. License compliance: Use only redistributable assets

🚀 Quick Start Example

Snake game (Rust + Macroquad)

1. Secure assets: Snake/food sprites from NAS, BGM/SFX from kenney.nl
2. Write TCs: 6 feature TCs, 5 UI TCs, 4 performance TCs
3. Implementation: Snake movement/collision/score logic with Macroquad
4. QA: Playwright automated tests + mobile manual tests
5. Deploy: eastsea.monster/games/snake/

Time required: Asset acquisition 1 hour + implementation 2 hours + QA 30 min = about 3.5 hours