wave3d-agent-sdk

/*! NOTICE-ID: WAVE-ENGINE-PROPRIETARY-NOTICE-v1 | Wave Engine Copyright (c) 2026 Wave3D. Proprietary; not open source. Licensed use only. No reverse engineering, decompilation, disassembly, AI-assisted implementation recovery, or notice removal except to the extent of non-waivable law. See LICENSE. */

Same-machine Wave Studio MCP transport plus one immutable WaveEngine authoring corpus.

License Boundary

Wave Engine is free-to-use proprietary software. It is not open source or source available. This package supports authoring through documented public APIs. It does not authorize implementation recovery. Controlling Wave Engine terms ship in dist/legal/.

Machine-readable policy IDs: WAVE-ENGINE-PROPRIETARY-NOTICE-v1 and WAVE-ENGINE-AI-POLICY-v1.

Start

npx -y [email protected] start

The SDK listens on loopback only. Localhost MCP uses no bearer token. Keep the Wave Studio tab open so its browser channel can rendezvous with the SDK.

Agent Flow

1. Call initialize.
2. Call self_check_wave_mcp with the version/build copied by Wave Studio.
3. Complete get_wave_agent_onboarding and accept_wave_agent_onboarding.
4. Call tools/list.
5. Pin the requested Studio tab with get_wave_session.
6. For an exact visible-code edit, call the Studio mutation tool directly. Do not run authoring discovery.
7. For unfamiliar WaveEngine authoring, call query_wave_authoring once with the user intent and bounded code context.
8. For a generated 3D model, texture atlas, or PBR material, call its concrete local SDK tool directly instead of authoring discovery.
9. Use returned authoring evidence or asset-generation workbench, then edit or operate Studio directly. Stateless structural preflight protects code mutations. Same-call operation diagnostics are authoritative; do not repeat a successful run without a new reason.

query_wave_authoring is the only authoring discovery tool. Atomic family/capability tags annotate unified records; they are not a routing hierarchy or second corpus. The package has no secondary search index, remote authoring lookup, legacy lookup tools, or triage path.

Exact public symbols and owner/member queries resolve from API Extractor maps. Natural intent, bounded code context, and compiler-error repair use the same deterministic local lexical projection over public APIs, authoring bodies, focused examples, concepts, and contracts. No embedding model, vector index, hosted lookup, or retrieval-time network path is present.

Authoring Doctrine

MCP teaches one Wave Engine pattern: choose a legitimate public authoring object, facade, factory, entity, component facade, or vocabulary object, then express the intent as one semantic method call or one fluent chain to its terminal. Prefer native Wave semantics for values, state, placement, animation, and lifecycle. Keep ordinary scene code synchronous and performance-aware.

The authored sources are wave-engine/docs/agentSkills/fundamentals/authoring-model.md and wave-engine/docs/agentAuthoring/contracts/authoring-constitution.json. The packaged corpus is a generated immutable projection; do not hand-edit it.

Asset Generation

Asset generation is a first-class local SDK workflow, not an API lookup and not a bootstrap.ts edit.

• 3D model: create_wave_3d_modeling_job -> author and run the returned private Python recipe -> inspect_wave_3d_model_artifact -> upload/bind only after acceptance.
• Texture atlas: compile_wave_atlas with operation:"prepare" -> create the planned PNG sources -> operation:"compile" -> inspect_wave_atlas_artifact -> upload/bind only after acceptance.
• PBR material: compile_wave_pbr_material with operation:"prepare" -> retrieve or generate one coherent aligned source set -> operation:"compile" -> inspect_wave_pbr_material_artifact -> upload only the accepted .wave-material.zip.

The model lane owns semantic material slots and simple embedded evidence. Generated high-fidelity reusable PBR maps use the separate material compile+inspect lane; model recipes must not invent or duplicate those image maps.

The package ships its pinned Wave adapter at dist/providers/compileArticraftMechanical.py. Normal SDK operation resolves that packaged copy automatically. Trusted Articraft imports additionally require WAVE_ARTICRAFT_PYTHON to name the administrator-provisioned pinned Articraft virtual-environment Python and WAVE_ARTICRAFT_RECORDS_ROOT to name the trusted records authority. WAVE_ARTICRAFT_MECHANICAL_COMPILER remains an explicit administrator override; end users never supply compiler scripts.

Atlas profiles are uiSkin, vfxFlipbook, foliageCards, spriteAnimation, staticMaskAtlas, and materialChannels. Compiler owns packing, padding, trim restoration, channel alignment, hashes, consumer projection, and QC. Agent must not hand-author atlas coordinates.

Commands

wave3d-agent-sdk --version
wave3d-agent-sdk start
wave3d-agent-sdk doctor
wave3d-agent-sdk cache status
wave3d-agent-sdk cache refresh
wave3d-agent-sdk cache clear

start, cache status, and cache refresh validate and atomically install the immutable package corpus when it is missing, corrupt, or different. A refresh of an already-valid identical bundle is idempotent. The CLI never rebuilds retrieval indexes and never downloads a corpus or retrieval model.

Corpus Contract

The package contains one hash-linked authoring snapshot with:

• API Extractor public contract evidence;
• public API, authoring-body, example, contract, concept, and relationship records;
• family and capability tags as metadata;
• serialized lexical Orama retrieval projection;
• Wave Engine legal SSOT copies and required runtime third-party notices.

Every public callable record must have an owning or supporting authoring body. Internal implementation, source locations, source maps, engine systems, and raw Babylon implementation surfaces are rejected by the package gate.

Security

• MCP binds to loopback only.
• Studio browser routes require a trusted Wave Studio origin.
• Corpus paths, counts, byte sizes, public-boundary evidence, lexical Orama projection, licenses, and hashes are validated before use.
• Failed corpus preparation prevents SDK startup.
• Cache clear refuses dangerous or unmarked custom paths.