이 페이지에서
프로젝트 설정
저장소 컨벤션은 권장 asset/ → 루트 build/ 배치를 정의합니다. 현재 소스에서는 같은 버전 2 객체를 내보내는 코드형 .ashfoxworkspace.mjs도 지원하며 다음 CLI 릴리스에 포함됩니다. 루트마다 설정 형식 하나만 사용하세요.
네이티브 .ashfox 파일이 영속적인 에셋 원본입니다. 워크스페이스는 선택 사항입니다. 공통 소스 선택·패키지·제외·빌드·출력 규칙이 필요할 때만 루트 .ashfoxworkspace를 사용하세요. 설정만 담으며 원본이나 컴파일 상태는 담지 않습니다. 모델·스프라이트·사운드 파일은 워크스페이스 없이 직접 컴파일할 수 있습니다.
npx --no-install ashfox build fox.ashfox --json
상위 설정이 없으면 CLI는 진입점과 파싱한 상대 import 의존성만 읽고, 진입점 옆의 dist/<asset-id>/build와 dist/<asset-id>/exports에 출력합니다. 워크스페이스 파일을 만들지 않습니다. 모듈은 빌드 진입점이 아닌 의존성입니다. import는 진입점 폴더 아래에 있어야 하며 패키지 import에는 설정된 프로젝트가 필요합니다. 관련 없는 파일은 스캔하지 않습니다.
CLI는 가장 가까운 .ashfoxworkspace를 위로 탐색하며 Git 루트나 파일시스템 루트에서 멈춥니다. 설정을 찾으면 직접 설정 파일을 넘겼을 때처럼 전체 프로젝트 규칙을 적용하고 프로젝트를 원자적으로 빌드합니다. 잘못된 설정을 무시하고 독립 파일 기본값으로 전환하지 않습니다.
items/
.ashfoxworkspace
src/
shared.ashfox
apple.ashfox
iron_sword.ashfox
build/ derived compiler output
exports/ delivery artifacts
완전한 아이템 프로젝트를 내려받아 압축을 푸세요. 설정은 examples/items/.ashfoxworkspace에 있고 원본은 examples/items/src/에 있습니다. 설정과 원본을 함께 Git에 보관하세요.
압축을 푼 예제 폴더에서 실행합니다.
npx --no-install ashfox check .ashfoxworkspace --json
npx --no-install ashfox build .ashfoxworkspace --json
npx --no-install ashfox verify build --json
CLI는 불변 번들과 출력 경로를 반환합니다. build/current.json으로 선택된 빌드를 확인하세요. 번들 해시를 추측하거나 수정 시각으로 고르지 마세요. 이 예제의 생성 폴더 build/와 exports/는 Git에서 제외됩니다.
루트 설정
{
"format": "ashfox-workspace",
"version": 2,
"name": "my-items",
"packages": [{
"name": "items",
"root": "src",
"manifest": {
"format": "ashfox-package",
"version": 1,
"entries": [{"name": "apple", "path": "apple.ashfox"}],
"modules": [{"subpath": "./shared", "path": "shared.ashfox"}],
"dependencies": []
}
}],
"include": ["src/**/*.ashfox"],
"ignore": ["src/drafts/**"],
"build": {"directory": "build"},
"exports": [{
"name": "apple_png",
"entry": {"packageName": "items", "entryName": "apple"},
"format": "png",
"directory": "exports/apple"
}]
}
설정이 있으면 허용되는 키와 필수 키가 정해져 있습니다. 루트가 소스 탐색, 진입점·모듈 등록, 로컬 패키지 의존성, 전달 설정을 담당합니다. 패키지 내부 파일 경로는 패키지 루트 기준이며 include·ignore·build·export 경로는 프로젝트 루트 기준입니다. 출력 위치는 픽셀이나 모델 형상에 영향을 주지 않지만, 위치를 바꾸면 프로젝트 빌드 식별자는 달라집니다.
include와 ignore는 *, **, ?를 지원합니다. **/ 접두사는 디렉터리 0개에도 대응합니다. ignore가 우선이며 부정 패턴이나 암묵적인 .gitignore 병합은 없습니다. .git, node_modules, .ashfox, build.directory, 모든 export 디렉터리는 소스 선택에서 제외됩니다. 루트 설정 자체는 소스 후보가 아닙니다. 선언한 진입점·모듈은 포함되고 제외되지 않아야 하며, ignore로 선언을 조용히 비활성화할 수 없습니다. 선택된 .ashfox가 미등록 상태라면 암묵적으로 컴파일하지 않고 거부합니다.
루트와 경로는 정규화되어 충돌하지 않아야 합니다. 절대 경로, 상위 경로 이동, 역슬래시, 출력 겹침, 예약 디렉터리 출력은 거부합니다. 소스 심볼릭 링크도 거부하며 생성물은 탐색에서 제외합니다. 출력 소유권은 설정된 대상에만 적용됩니다. include나 ignore가 삭제 권한을 부여하지는 않습니다.
설정은 스프라이트의 PNG, 모델의 GLB·Java block·GeckoLib 5·Bedrock, 사운드의 WAV를 지원합니다. Minecraft 포맷 java_block, geckolib5, bedrock은 namespace와 확장자 없는 modelPath가 추가로 필요합니다. 출력 포맷을 참고하세요. 종류와 포맷이 맞지 않으면 전체 후보가 실패합니다.
출력 설정
모든 export에는 name, entry, format, directory가 필요하고 entry는 packageName과 entryName을 가집니다. 스프라이트는 png, 사운드는 wav, 일반 모델은 glb를 사용하세요. GLB는 선택적으로 encoding: portable|optimized를 받으며 CLI 기본값은 portable입니다. Minecraft 모델 출력에는 공통 필드 외에 namespace와 확장자 없는 modelPath가 필요합니다.
export·패키지·진입점 이름은 소문자로 시작하고 소문자·숫자·밑줄만 사용하며 최대 48자입니다. 프로젝트 이름에는 하이픈도 허용합니다. 이름은 에셋 식별자이므로 export 이름을 바꾸면 팩의 참조도 갱신해야 합니다.
게임 전달물 구성하기
이름 있는 export와 팩 연결의 개수 상한은 없습니다. 관련 에셋은 같은 워크스페이스에 보관하세요. 64개를 넘기기 위해 나눌 필요는 없습니다. CLI의 실행 예산은 계속 적용됩니다.
루트에 선택적인 packs 배열을 추가해 export를 조합합니다. GLB·PNG·오디오와 런타임 매니페스트는 게임 에셋, Java 리소스 경로와 사운드 이벤트는 Minecraft 팩을 사용하세요. 둘을 함께 사용할 수 있습니다. 팩과 export를 통틀어 이름이 고유해야 합니다. 팩의 source는 소스 파일명이 아닌 export 이름을 가리킵니다.
위 패키지 선언은 스프라이트 가이드의 apple 및 shared 모듈과 함께 복사하면 완전한 예제입니다. 포함되는 모든 소스를 진입점이나 모듈로 등록하세요. 모듈은 진입점에서 도달 가능해야 하며 사용되지 않는 선언은 오류입니다. dependencies는 모델 패키지 import용 로컬 의존성을 선언할 뿐 원격 패키지를 설치하지 않습니다. 스프라이트 import는 상대 경로를 사용합니다.
예측 가능한 빌드
네이티브 CLI는 설정 버전 2와 외부 .ashfox 소스를 받습니다. 내용은 소스 파일에, 설정은 루트 설정에 저장하세요. 알 수 없는 키와 소스에 포함된 워크스페이스 객체는 거부합니다.
소스 선택은 512개 파일·8 MiB, 설정은 256 KiB, 파일시스템 스캔은 20,000개 항목으로 제한됩니다. 소스 심볼릭 링크는 거부합니다. 대규모 프로젝트는 생성 트리를 포함하는 대신 설정 루트를 나누세요. 실행 제한은 CLI 레퍼런스, 발행·소유권·정리는 저장과 출력을 참고하세요.