에셋 빌드 자동화

원본·출력 배치, 코드형 설정, 게임 어댑터의 구체적인 규칙은 저장소 컨벤션을 참고하세요.

게임 저장소에 컴파일러 패키지와 원본을 고정합니다. OGG를 사용한다면 CI의 FFmpeg 빌드도 고정하세요. 의존성이 없을 때 관계없는 패키지를 내려받지 않도록 로컬에 설치된 실행 파일을 사용합니다.

원본 소유권, PR 검토 자료, 릴리스 운영은 Assets as Code부터 확인하세요.

빌드 단계 추가하기

CLI tarball 설치 후 게임 프로젝트의 package.json에 스크립트를 추가합니다.

{
  "scripts": {
    "assets:check": "ashfox check assets/.ashfoxworkspace --json",
    "assets:build": "ashfox build assets/.ashfoxworkspace --json",
    "assets:verify": "ashfox verify assets/dist/build --json"
  }
}

기존 패키지 파일에 필드를 합치세요. 파일 전체를 교체하는 예제가 아닙니다. 입력 경로와 검증 디렉터리는 실제 설정에 맞게 바꿉니다.

게임 빌드 전에 assets:build와 assets:verify를 실행하세요. 종료 코드가 0이 아니면 파이프라인을 중단합니다. 명령은 stdout에 JSON을 출력하므로 필요하면 빌드 응답을 증거로 보관합니다.

반환된 경로 사용하기

설치된 CLI를 사용하는 최소 Node 빌드 단계입니다.

const { execFileSync } = require('node:child_process');
const path = require('node:path');
const cli = path.resolve('node_modules/@ashfox/cli/dist/ashfox.cjs');
const run = (...args) => JSON.parse(execFileSync(process.execPath, [cli, ...args, '--json'], { encoding: 'utf8' }));
const built = run('build', 'assets/.ashfoxworkspace');
if (!built.ok) throw new Error(JSON.stringify(built.diagnostics));
const pack = built.result.exports.find(entry => entry.id === 'voxel_game');
if (!pack) throw new Error('Missing configured pack');
console.log(pack.directory); // Pass this exact immutable directory to your copy/import step.

Node를 직접 실행하므로 셸 실행 파일 연결 방식이 다른 환경에서도 사용할 수 있습니다. 명령이 실패하면 execFileSync가 예외를 던집니다. 실패한 빌드를 성공한 것처럼 취급해 어제의 팩을 사용하지 마세요. 별도의 verify 호출로 선택된 정식 번들을 검사하고, 소비 작업이 끝날 때까지 같은 빌드 해시를 유지합니다.

재현성과 동시 실행

원본·설정, 번들에 포함된 컴파일러, 실행 프로필이 빌드 식별자에 반영됩니다. OGG에는 인코더 지문도 추가됩니다. 같은 프로필로 깨끗한 출력 폴더에서 다시 빌드하면 번들 해시가 같아야 합니다. Node·V8·OS·아키텍처·인코더 프로필이 다르면 일치를 보장하지 않습니다.

연산 캐시나 watch 모드는 없습니다. 기존 불변 결과물도 다시 계산한 뒤 검증합니다. 파일 감시 도구나 프로젝트 빌드 시스템에서 CLI를 호출하되, 같은 출력 디렉터리에 쓰는 작업이 겹치지 않도록 하세요. 같은 위치를 대상으로 동시 빌드하면 종료 코드 4로 실패합니다.

배포 경계

검증된 불변 팩의 업로드나 복사는 별도 게임 빌드 단계에서 수행합니다. CLI는 서버를 배포하거나 사용자에게 설치된 게임을 수정하거나 패키지를 공개하지 않습니다. ZIP이 필요하면 archive: true를 선택하고, 그렇지 않으면 출력 폴더를 사용하세요. 런타임 영수증이나 생성물 대신 원본을 버전 관리합니다.