Math Worms

What

Worms, 포트리스, Angry Birds에서 영감을 받은 턴제 전략 게임. 수학 함수를 발사체 궤적으로 변환하여, 플레이어가 함수식을 입력해 상대를 공격한다. Phaser 4와 Matter.js 물리 엔진 위에서 동작하며, CortexJS Compute Engine으로 수식을 파싱하고 MathLive로 입력받고 KaTeX로 렌더링한다.

Why

학생들이 함수의 그래프 형태를 직관적으로 이해하지 못하는 문제. 교과서의 정적인 그래프 대신, 자신이 입력한 함수가 포탄 궤적이 되어 날아가는 경험을 통해 함수 개념을 체득하게 한다.

How

핵심은 6계층 Expression Pipeline이다. 사용자가 입력한 함수식을 AST로 파싱한 뒤, 디버프 변환·좌표 변환·방향 반전까지 6단계를 거쳐 월드 좌표의 궤적으로 변환한다. 목표물을 맞추는 과정에서 학생들은 자연스럽게 다양한 함수의 그래프 형태, 평행이동, 대칭이동 개념을 체험한다. 디버프 시스템이 함수를 변환시키면서 변환 개념까지 게임 속에서 익힌다.

Impact

단원별로 배우는 함수에 맞춰 맵을 설계하여, 해당 함수의 궤적을 정밀하게 조정해야만 상대를 공격할 수 있는 수학적 맥락을 제공할 계획이다. 수업 도구로 활용하여 함수 학습 동기를 부여하는 것이 목표.

Tech Stack

• Game Engine: Phaser 4 + Matter.js 물리 엔진
• Language: TypeScript 5 strict mode
• Math: CortexJS Compute Engine (AST 파싱/평가) + MathLive (수식 입력) + KaTeX (수식 렌더링)
• Build: Vite 6
• Test: Playwright E2E
• Lint: Biome
• Deploy: GitHub Pages (GitHub Actions CI/CD)

Architecture

Phaser 4의 씬 시스템(Boot→Menu→Game→UI) 위에 게임 로직을 구축했다. 물리 연산은 Matter.js가 담당하고, 수식 처리는 Expression Pipeline이 전담한다. 좌표계 분리가 핵심 설계다. 물리 엔진은 canonical world 좌표를 유지하고, PresentationMirror가 RenderTexture 기반으로 시각만 반전시켜 플레이어가 항상 좌→우 방향으로 함수를 입력할 수 있게 한다. ViewNormalizer가 반전된 화면의 포인터 좌표를 정규화한다.

Decision 1: CortexJS Compute Engine + MathLive + KaTeX 조합

Context: 사용자가 입력한 수학 함수식을 파싱하고, 게임 내에서 변환하고, 화면에 렌더링해야 한다. 세 가지 역할이 모두 필요. Decision: 같은 CortexJS 생태계의 Compute Engine(AST 파싱/평가)과 MathLive(입력 UI)를 선택하고, 렌더링은 KaTeX를 사용. math.js 대신 CortexJS를 택한 이유는 MathJSON AST 기반의 자연스러운 연동. Consequence: 3개 라이브러리의 AST/LaTeX 포맷 차이를 맞추는 변환 레이어가 필요했지만, AST 레벨에서 디버프가 수식을 변환하는 게임 메카닉이 가능해졌다.

Decision 2: 6계층 Expression Pipeline 설계

Context: 단순히 함수를 평가하는 것이 아니라, 디버프·좌표 변환·방향 반전 등 게임 메카닉이 수식 평가 과정에 개입해야 한다. Decision: f_user→T_debuff→originWorld→hLocal→kLocal→dir 6단계 파이프라인으로 분리. Consequence: 각 계층이 독립적이어서 디버프 추가나 좌표계 변경이 다른 계층에 영향을 주지 않는 확장 가능한 구조가 되었다.

Decision 3: PresentationMirror 시각 반전 아키텍처

Context: Phaser 4에서 Layer는 scale 불가, Container는 physics children에 영향을 줘서, 화면 반전 방법이 제한적이었다. Decision: RenderTexture 단일 객체로 구현. 물리 엔진은 canonical world 유지, presentation 계층에서만 setFlipX로 거울 반사. Consequence: 플레이어가 항상 자기 시점에서 좌→우로 함수를 보면서도, 물리 연산은 영향받지 않는 깔끔한 분리를 달성.

배운 점

CortexJS Compute Engine의 AST(MathJSON)를 다루면서 수학 표현식의 구조적 처리 방법을 익혔다. 파싱→변환→평가로 이어지는 파이프라인을 설계하면서, 컴파일러와 유사한 단계적 처리 아키텍처를 게임에 적용하는 경험을 했다. Phaser 4의 씬 관리, RenderTexture, Matter.js 물리 바디 관리 등 게임 엔진 아키텍처 전반을 학습했다. 특히 물리 계층과 프레젠테이션 계층을 분리하는 설계가 게임 개발의 핵심이라는 것을 체감했다.

실패한 시도

특별히 버린 설계는 없다. 11 Phase 계획을 세우고 순차적으로 진행하여 대부분 계획대로 완성했다.

2026-04 — 프로젝트 시작 및 11 Phase 완성

PLAN.md v4로 6계층 수식 모델, PresentationMirror, ViewNormalizer를 포함한 전체 아키텍처를 설계하고, 하루 집중 개발로 Phase 0~10까지 구현 완료. GitHub Pages 자동 배포 파이프라인 구성.