이 페이지에서
Assets as Code
실제 원본·출력 배치, 코드형 설정, 게임 어댑터는 저장소 컨벤션을 따라 구성하세요.
Assets as Code는 편집 가능한 에셋 정의를 소스로 보관하고, 버전 관리에서 변경을 리뷰하며, 배포할 결과물을 컴파일하는 방식입니다. Ashfox는 복셀 게임의 모델·픽셀 텍스처·절차적 사운드를 네이티브 .ashfox 소스와 하나의 CLI로 다룹니다.
Git은 원본의 이력을 기록하고 Ashfox는 에셋을 컴파일·검사합니다. 실행 시점과 결과물의 전달 위치는 프로젝트의 CI와 게임 빌드가 결정합니다.
에셋 하나로 시작하기
설치와 첫 PNG 만들기를 따라가세요. 원본과 가져오는 모듈을 게임 저장소에 보관합니다. 에셋 하나에는 워크스페이스가 필요 없습니다. 공통 선택 규칙이나 전달 설정이 필요할 때 .ashfoxworkspace를 추가하세요. 프로젝트 설정을 참고하세요.
아이템 다음에는 홈페이지의 원본이 제공되는 예제를 살펴보세요. Griffin은 관절이 있는 날개와 여섯 가지 동작을 보여주며, 여우와 고블린은 더 작은 애니메이션 예제입니다. 원본과 출력 모델을 함께 확인하세요. 빌드 리플레이는 완성된 에셋의 구성을 재현하며 에이전트 편집 과정의 녹화가 아닙니다.
원본과 결과물 구분하기
| Git에 보관 | 빌드 또는 릴리스에 보관 |
|---|---|
.ashfox 진입점과 가져오는 모든 모듈 |
출력 GLB·PNG·WAV·OGG·ZIP |
선택적인 .ashfoxworkspace와 전달 설정 |
빌드 영수증·카탈로그·반환된 정확한 출력 경로 |
CLI를 고정하는 package.json과 package-lock.json |
소스 커밋·컴파일러 버전·실행 프로필 |
| CI 스크립트와 게임 통합 코드 | 해당 소스 커밋의 캡처와 동작 미리보기 |
실제 설정에 맞춰 생성 디렉터리를 Git에서 제외하세요. 직접 제작한 파일도 있을 수 있으므로 모든 PNG나 WAV를 전역으로 제외하지 마세요. 결과물을 별도의 편집 원본으로 삼지 말고 소스를 수정한 뒤 다시 빌드하세요. 문서용 생성 예제를 공개하는 것은 명시적으로 결정하는 별도 배포 방식입니다.
리뷰할 수 있는 변경 만들기
- Git 브랜치를 만들고 날개 동작, 아이템 팔레트, 충돌음 하나처럼 범위가 명확한 변경을 에이전트에게 요청합니다. 대상 게임을 함께 알려주세요.
- 편집 전 진입점과 가져오는 모듈을 확인하고 관련 없는 에셋은 보존합니다.
- CLI 검사를 실행합니다. 유용한 모델 시점을 캡처하고, 텍스처를 원래 해상도로 확인하며, 바뀐 동작을 재생하고 사운드를 들어봅니다.
- 소스를 커밋하고 PR에 검토 자료를 첨부합니다. 소스 커밋, 관련 에셋 ID, 도구 환경, 게임에서 확인하지 못한 동작을 명시합니다.
- 텍스트 diff와 결과물을 함께 리뷰합니다. 컴파일 성공은 기술적 유효성을 보여줄 뿐 시각적 품질이나 게임 적합성을 보장하지 않습니다.
- 병합 후 깨끗하고 버전이 고정된 환경에서 병합된 소스를 빌드합니다. 검증한 뒤 반환된 불변 출력 디렉터리를 게임 빌드에 전달합니다.
소스가 바뀌면 검토 자료도 갱신하세요. 이전 커밋의 캡처를 현재 PR 결과처럼 표시하지 마세요. 브랜치 미리보기가 승인되었다고 이후 병합 빌드가 같다는 뜻은 아닙니다.
에이전트 작업 흐름은 편집 반복 과정을, 검사와 캡처는 시점·픽셀·동작·stdio를 설명합니다.
로컬 흐름이 동작하면 CI 추가하기
빌드 자동화의 스크립트로 시작하세요. npm ci로 고정 패키지를 복원하고 게임 빌드 전에 check·build·verify를 실행합니다. 종료 코드가 0이 아니면 에셋 빌드 실패로 처리합니다. 이전 실행의 오래된 출력 대신 성공한 빌드에서 반환한 정확한 경로를 사용하세요.
CLI와 Node, OS·아키텍처, OGG 생성 시 FFmpeg를 포함한 실행 환경을 고정합니다. 재현성은 같은 도구와 실행 프로필 범위에 한정되며 임의의 머신 사이에서 바이트 일치를 약속하지 않습니다. 동시 작업은 서로 다른 출력 디렉터리를 사용하세요.
PR 작업은 읽기 전용 권한으로 검증과 리뷰 자료 생성을 수행합니다. 신뢰되지 않은 PR 실행에 릴리스 자격 증명을 제공하지 마세요. 캡처와 빌드 증거는 CI 아티팩트로 올리고, 게임 결과물은 별도의 신뢰된 작업에서 공개합니다. Ashfox는 PR 봇 설치, Git 커밋 생성, 원격 상태의 지속적인 동기화, 게임 자동 배포를 수행하지 않습니다.
릴리스와 복원 계획하기
전달하는 결과물마다 소스 커밋과 빌드 식별자를 연결합니다. 게임이 실제로 받은 검증된 패키지를 보관하세요. 롤백할 때는 보관한 패키지를 선택하거나 이전 소스와 그에 맞는 도구 환경을 복원해 다시 빌드·검증합니다. 소스만 되돌려도 이미 배포된 게임이 바뀌지는 않습니다.
게임에서는 크기, 방향, 애니메이션 이름, 아이템 ID, 사운드 이벤트 매핑을 확인하세요. 게임 번들, Minecraft 팩, 실행 가능한 예제를 참고하세요.
이 작업 흐름의 배경
작성·미리보기·리뷰 흐름은 OpenTofu의 핵심 작업 흐름을 참고했습니다. 리뷰 시점의 검사와 전달을 분리하는 방식은 Pulumi의 지속적 전달 안내를 참고합니다. CI 권한과 신뢰되지 않은 변경에는 GitHub 보안 사용 지침을 따르세요. 이들은 운영 방식의 참고 자료이며 Ashfox가 설치하는 통합 기능은 아닙니다.