Checkpoint 3: deliver playable samples and complete native authoring workflows
This commit is contained in:
Emil
@@ -0,0 +1,120 @@
|
||||
# Assets and Blender
|
||||
|
||||
Keep source assets under your project's `Assets` directory. Faset imports PNG/JPEG,
|
||||
static glTF/GLB, and manifests published by the optional Blender helper. The import
|
||||
service runs in the Editor; exported games load cooked data and need no Blender.
|
||||
|
||||
## Import a model
|
||||
|
||||
1. Copy a `.glb`, or a `.gltf` with its relative buffers and images, into `Assets`.
|
||||
2. In the **Assets** panel select the source and use **Import**. Watch the job state
|
||||
and diagnostics. Import is asynchronous; the previous working generation stays
|
||||
available until a complete replacement is ready.
|
||||
3. Place the imported scene in the viewport. The Faset object stores the AssetId;
|
||||
its transform, gameplay components, and physics remain authoring data.
|
||||
4. Add a rigid body explicitly if needed. Import does not infer gameplay collisions
|
||||
from the visual mesh.
|
||||
|
||||
The same operation works through the command line:
|
||||
|
||||
```sh
|
||||
build/linux-debug/faset_editor --project MyGame --command \
|
||||
'{"name":"faset_import","arguments":{"path":"Assets/door.glb"}}' --wait
|
||||
```
|
||||
|
||||
With MCP, call `faset_import`, then query `faset_job` using the returned job ID.
|
||||
`faset_job_cancel` requests cancellation. Cancelling an import does not Undo an
|
||||
authoring edit. See [MCP and CLI](mcp.md) for transport setup and errors.
|
||||
|
||||
## Import an image
|
||||
|
||||
PNG and JPEG become image assets. Drag an imported image into a scene to create a
|
||||
sprite. `pixels_per_unit` is a positive import setting, defaulting to 100; it controls
|
||||
the sprite's natural size. Color, transform, and layer remain scene properties.
|
||||
|
||||
```json
|
||||
{"name":"faset_import","arguments":{
|
||||
"path":"Assets/player.png","settings":{"pixels_per_unit":32}
|
||||
}}
|
||||
```
|
||||
|
||||
Omitting `settings` reuses the saved recipe. Providing an object replaces the recipe;
|
||||
it is not a partial merge. Malformed or oversized images produce diagnostics and
|
||||
retain the last successful generation.
|
||||
|
||||
## Use the optional Blender helper
|
||||
|
||||
The helper works in unmodified Blender. Blender 4.5.3 LTS is the version used for
|
||||
the observed round-trip test. Ordinary GLB import remains available without it.
|
||||
|
||||
1. Zip the repository's `tools/blender_addon` directory with that directory at the
|
||||
ZIP's top level. Install the ZIP through Blender's add-on preferences and enable
|
||||
**Faset GLB Export**.
|
||||
2. Build a static scene using ordinary meshes and glTF-compatible PBR materials.
|
||||
3. Choose **File → Export → Faset GLB Bundle** and place `manifest.json` in a directory
|
||||
inside the Faset project's `Assets` directory.
|
||||
4. **Save the `.blend` after the first export.** The helper assigns `faset_id` custom
|
||||
properties to objects, meshes and materials, and `faset_asset_id` to the scene.
|
||||
5. Import the exported `manifest.json` in Faset. Keep the manifest and its
|
||||
`payload/<sha256>.glb` files together.
|
||||
|
||||
The helper publishes the manifest only after the payload is complete. It exports
|
||||
the active Blender scene, not just the current selection. Gameplay and physics
|
||||
components are added in Faset and are never written by the Blender helper.
|
||||
|
||||
## Rename, duplicate, and reimport
|
||||
|
||||
Renaming an object with a saved `faset_id` preserves its source identity. Re-export
|
||||
and reimport update the shared asset; scene placements using that AssetId load the
|
||||
new geometry while keeping their own transforms and components.
|
||||
|
||||
Duplicating an object can also duplicate its custom ID. The exporter rejects
|
||||
ambiguous IDs. Select the new copy and run **Faset: New IDs for Selected**. Shared
|
||||
mesh datablocks remain shared. Repair deliberately duplicated material IDs in
|
||||
Blender's Custom Properties. Save the `.blend` again.
|
||||
|
||||
Removing an exported output produces an import conflict. Faset keeps the old
|
||||
generation active. Inspect the diagnostics and update affected references before
|
||||
explicitly importing with `allow_removed_outputs: true`. This accepts removal;
|
||||
it does not automatically remap references. A normal GLB without persistent custom
|
||||
IDs uses structural matching, which cannot guarantee identity after rename or
|
||||
restructuring.
|
||||
|
||||
## Coordinates and supported content
|
||||
|
||||
The static profile uses right-handed glTF coordinates: metres, Y up. The Blender
|
||||
helper enables glTF's Y-up conversion; do not add a second manual axis conversion.
|
||||
Transforms and hierarchy are retained. Physics currently supports explicit boxes
|
||||
on root-level objects. A visual imported mesh is not a mesh collider.
|
||||
|
||||
The renderer uses static triangle meshes, UV0, base-color factor/texture, metallic
|
||||
and roughness factors, and directional light/shadows. Import can retain additional
|
||||
glTF material metadata, but normal/occlusion/emissive/metallic-roughness texture maps,
|
||||
glTF alpha-mode selection, unlit selection and per-material face-culling behavior
|
||||
are not all implemented in the baseline renderer. Diagnostics identify unsupported
|
||||
material features. Procedural Blender node networks need baking or simplification.
|
||||
Skinning, animation playback, morph targets and compressed geometry are outside this
|
||||
profile. Imported material records use the versioned `faset.material` format inside
|
||||
the asset manifest; a standalone material editor is later work.
|
||||
|
||||
## What to commit and how to rebuild caches
|
||||
|
||||
Commit your source files, Blender bundle manifests/payloads, and
|
||||
`<source>.faset-import.json` sidecars. Sidecars preserve AssetId and import settings.
|
||||
Also commit `<source>.faset-overrides.json` if used. Commit `.blend` sources when they
|
||||
are part of your project. Do not commit `.faset/cache`.
|
||||
|
||||
After clearing the cache or cloning a project, import the same sources again. Their
|
||||
sidecars restore identities and recipes. Rebuild C++ to restore gameplay metadata.
|
||||
Deleting the **entire** `.faset` directory also removes recovery journals and local
|
||||
editor state; preserve unsaved work before doing that. An export fails if a referenced
|
||||
asset has not yet been rebuilt.
|
||||
|
||||
The cache key includes source/dependency hashes, settings, importer recipe, pinned
|
||||
importer dependencies and the desktop target profile. Linux and Windows share this
|
||||
portable content profile; runtime executable builds remain platform-specific.
|
||||
|
||||
For an end-to-end example, open `examples/projects/collect-3d`. Its exit arch includes
|
||||
a `.blend`, reproducible Blender script and a published bundle. The repository's
|
||||
`tools/verify_blender_roundtrip.py` runs the actual Blender helper and Editor imports
|
||||
to check rename, geometry changes, removal conflicts and failure preservation.
|
||||
Reference in New Issue
Block a user