Separate world, volumetric, block, and avatar SDK surfaces#36
Merged
Conversation
* Reshape SDK public world surface Introduce dedicated block and volumetric SDK type crates, decompose freven_world_api into focused modules, and update guest-facing crates and workspace metadata to match the new public surface boundaries.
* Add volumetric addressing foundation types Introduce stable volumetric addressing value types in freven_volumetric_sdk_types, split topology helpers into their own module, and migrate worldgen request/write contracts across world_api and world_guest to use the new column, section, and world-cell vocabulary. * cargo fmt
* Clarify block vocabulary ownership Document that standard block/profile ids and descriptors are owned by freven_block_sdk_types, while freven_world_api and freven_world_guest only consume that vocabulary through world-facing surfaces. Refresh crate docs, trait comments, and examples to make the layer boundaries explicit. * Extract block gameplay contracts from world APIs Introduce freven_block_guest and freven_block_api as the dedicated homes for runtime-loaded and builtin block gameplay contracts, then rewire freven_world_api, freven_world_guest, and freven_world_guest_sdk to consume those surfaces instead of owning them directly. This makes block mutation/query ownership explicit, narrows world-level service families, and keeps the public SDK layering aligned with the standard block gameplay split. * Clarify block contract ownership and composition Refresh SDK and ABI documentation to state that block vocabulary lives in freven_block_sdk_types, runtime-loaded block query and mutation contracts live in freven_block_guest, and world-facing APIs only compose over those block-owned families. Update examples and comments to reflect RuntimeOutput.blocks and the WorldServiceRequest::Block service family consistently. * Clarify SDK ownership layers Update the top-level SDK docs, world API README, and guest/native/wasm ABI references to describe the explicit split between generic world, volumetric, and reusable block-owned surfaces. Make the carrier role of world-owned envelopes over block-owned payload families explicit and align all documentation with RuntimeOutput.blocks terminology. * fmt/clippy fix
Introduce freven_avatar_sdk_types and freven_avatar_api as the public home for avatar identity, control, controller, lifecycle, and presentation contracts. Move avatar-facing client and controller surfaces out of freven_world_api, keep world ownership boundaries explicit, and add hidden registration hooks so avatar-owned extensions can register through ModContext without leaving those contracts world-owned.
* Align guest provider ownership model Group guest registration and provider callbacks into explicit world and avatar families in the public guest contract and SDK exports. This keeps the runtime-facing schema aligned with the Stage 4.7 ownership split. * Trim guest action and query contracts Remove the ad-hoc player position field from action inputs and drop entity/component query variants from the public guest contract so Stage 4.7 keeps runtime-facing surfaces aligned with explicit ownership boundaries.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR formalizes the public SDK ownership split that had previously been blurred inside the world-facing surface. It introduces explicit avatar-, volumetric-, and block-owned crates, narrows
freven_world_*back to generic world concerns, and refreshes the public contracts and docs so downstream runtime, engine, and vanilla code can depend on the correct layer.What changed
freven_avatar_sdk_typesfreven_avatar_apifreven_volumetric_sdk_typesfreven_block_sdk_typesfreven_block_guestfreven_block_apifreven_world_sdk_typesintofreven_block_sdk_types.freven_world_sdk_typesintofreven_volumetric_sdk_types.freven_world_apiinto clearer world-owned modules and repositioned it as a composition layer over lower-level block/volumetric surfaces rather than the owner of those semantics.freven_world_guest, guest contract docs, native ABI docs, and Wasm ABI docs to preserve the ownership split while still allowing generic world envelopes to carry block-specific payload families where needed.Why
The previous SDK layout made it too easy to treat world, voxel, block, and avatar concepts as one undifferentiated surface. That made ownership ambiguous for downstream runtime code and obscured which crates should remain stable public contracts versus which ones are merely composition points. This change makes those boundaries explicit and gives the rest of the stack a cleaner contract to build on.
Notes for reviewers
The main thing to review here is semantic ownership, not just crate movement. The important question is whether each public type now lives in the layer that truly owns it and whether the remaining
freven_world_*surface is generic enough to stay world-owned without absorbing block- or topology-specific truth.