> For the complete documentation index, see [llms.txt](https://clunk.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://clunk.gitbook.io/docs/undefined-2/contracts.md). # 계약과 상태 Clunk 검사 결과의 규칙·점수·증거 상태를 읽는 개발자 참고 Clunk의 기본 검사 규칙은 `clunk-game-ready-v1` 버전 `1.0.0`입니다. 결과는 실제 GLB·glTF 바이트에서 계산하며, 파일 지문과 결과 지문을 함께 반환합니다. ## 점수와 준비 상태 점수는 0\~100이고 기본 `readyScoreThreshold`는 90입니다. `ready`가 되려면 다음 세 조건이 모두 맞아야 합니다. 1. 점수가 90 이상입니다. 2. `ERROR`·`CRITICAL` finding이 없습니다(`hardBlockerCount = 0`). 3. 남은 finding이 모두 `INFO`입니다. 화면은 이 결과를 다음 세 상태로 읽기 쉽게 나눕니다. | 상태 | 조건 | 의미 | | ------------------- | -------------------------- | ------------------------- | | `ready` · 통과 | 위 세 조건 충족 | 선언한 파일 정책을 만족합니다. | | `conditional` · 조건부 | 막는 문제는 없지만 경고 또는 기준 미달이 남음 | 안전한 수정만으로 모두 해결된 것은 아닙니다. | | `blocked` · 막힘 | `ERROR` 또는 `CRITICAL` 존재 | 현재 파일을 그대로 통과시키지 않습니다. | `WARNING`과 물리적 측정 finding은 의도에 따라 달라질 수 있으므로, `valid`나 점수만 보지 말고 finding의 `ruleId`, `severity`, `observed`, `threshold`를 함께 읽으세요. ## 네 증거 칸 파일 구조와 게임 화면은 한 판정이 아닙니다. | 필드 | 무엇을 뜻하나 | 기본 상태 | | --------------------------------- | ---------------- | ---------------------------- | | `STATIC` 또는 구조 | 바이트·형식·정책을 읽은 결과 | 검사 실행 뒤 값이 생김 | | `RUNTIME` 또는 `visualRuntime` | 실제 엔진에서 그린 화면 증거 | `GAP` 또는 `UNAVAILABLE` | | `PLAYER FACING` 또는 `playerFacing` | 게임 시점에서 본 화면 증거 | `NOT_EVALUATED` | | `HUMAN` 또는 `humanDecision` | 사람이 남긴 최종 판단 | `PENDING` 또는 `NOT_EVALUATED` | 구조 점수가 통과해도 `visualRuntime`, `playerFacing`, `humanDecision`을 자동으로 `PASS`로 바꾸지 않습니다. 캡처·엔진 runner·사람 판단이 실제로 없으면 그 상태를 그대로 보존합니다. ## 검사 evidence 예시 ```json { "schema": "clunk.asset-inspection-evidence.v2", "evidenceKind": "CONTRACT_FIXTURE", "inputHash": "", "resultDigest": "", "byteLength": 680412, "coreBuildId": "0.1.0", "ruleSetId": "clunk-game-ready-v1", "ruleSetVersion": "1.0.0", "profileId": "pc", "inspectionRunId": "run-2026-09-07-001", "qualityPolicy": { "requireRuntimeEvidence": "ADVISORY" }, "findings": [] } ``` `CONTRACT_FIXTURE`는 구조 evidence만 담습니다. `PLAYER_FACING_CAPTURE`는 캡처 바이트와 그 지문이 필요하고, 캡처가 있다고 사람의 승인을 추측하지 않습니다. ## Passport 안전한 수정의 Passport는 원본·출력의 증거를 연결합니다. ```json { "passportId": "passport--", "ruleSetId": "clunk-game-ready-v1", "sourceHash": "", "outputHash": "", "sourceInspectionDigest": "", "outputInspectionDigest": "", "operations": [] } ``` `outputHash`가 fresh output reinspection의 `inputHash`와 같아야 합니다. 원본을 덮어쓰거나, 다시 검사하지 않은 출력 파일을 Passport에 연결하면 증거가 아닙니다. ## Multi-file bundle HTTP MCP 또는 로컬 AssetOps에서 Spine JSON·atlas·PNG 같은 여러 파일을 검사할 때는 entry 파일과 관계를 보존합니다. ```json { "schema": "clunk.asset-inspection-request.v2", "entryFileName": "skeleton.json", "fileCount": 3, "files": [ { "path": "skeleton.json", "role": "spine-json", "relatesTo": ["atlas.atlas"] }, { "path": "atlas.atlas", "role": "atlas", "relatesTo": ["texture.png"] }, { "path": "texture.png", "role": "texture", "relatesTo": [] } ] } ``` HTTP는 로컬 절대 경로를 읽지 않으며, 파일 하나는 `fileName` + `bytesBase64`, bundle은 `entryFileName` + `files[]` 형식으로 보내야 합니다. ## Clunk Series 상태 Clunk Series는 외부 생성 API의 성공을 그대로 노출하는 이름이 아닙니다. Clunk가 감사한 자료와 내부 authoring rail을 실행하며 provider는 `clunk-series-native-v1`로 기록합니다. 현재 결과에는 `productionReady: false`와 `DRAFT_ONLY`가 남을 수 있습니다. 다음 증거를 모두 따로 확인하기 전에는 결과를 게임 출시 승인이나 판매 가능 상태로 부르지 않습니다. * 실제 입력·출력 바이트와 source/output hash * parse·structure·policy·blocker·score * optimize 뒤 fresh output reinspection * Passport와 다운로드 artifact reopen * shipped runtime, player-facing 화면과 사람의 판단 * provenance와 license [CLI와 CI](/docs/undefined-2/cli-ci.md)에서 `series:mesh`와 로컬 명령을 확인하고, [에셋 제작](/docs/undefined/create.md)에서 웹 제작 흐름을 확인하세요. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://clunk.gitbook.io/docs/undefined-2/contracts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.