Document terrain interaction contract v2

README.md

@@ -42,6 +42,12 @@ That document explains how a game such as Vanilla can provide a friendly
 blocktype/worldproperty workflow while the engine still consumes the generic
 canonical content graph.
 
+For the long-term voxel terrain break/place intent contract, see
+[docs/TERRAIN_INTERACTION_CONTRACT_v2.md](docs/TERRAIN_INTERACTION_CONTRACT_v2.md).
+That document defines the SDK-level action identity, ray, hit, prediction,
+server-validation, and reconciliation semantics that replace legacy
+target-position-only terrain interaction behavior for rc10.
+
 The current long-term direction is:
 
 - **engine/platform layer**: neutral runtime/platform substrate

crates/freven_block_api/src/lib.rs

@@ -65,6 +65,104 @@ pub struct ClientCursorHit {
     pub distance_m: f32,
 }
 
+/// Long-term terrain break/place action kind.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum TerrainInteractionKindV2 {
+    Break,
+    Place,
+}
+
+/// Client prediction transaction id for a terrain interaction.
+///
+/// This id is scoped by the surrounding `(level_id, stream_epoch, action_seq)`
+/// action identity. It is not a global terrain edit id.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct TerrainPredictionTransactionIdV2(pub u64);
+
+/// Identity and dependency boundary for Terrain Interaction Contract v2.
+///
+/// This is SDK vocabulary for builtin/block interaction surfaces. It is not yet
+/// a serialized action payload schema by itself.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TerrainInteractionIdentityV2 {
+    pub level_id: u32,
+    pub stream_epoch: u32,
+    pub input_seq: u32,
+    pub action_seq: Option<u32>,
+    pub kind: TerrainInteractionKindV2,
+    pub prediction_tx: TerrainPredictionTransactionIdV2,
+    pub depends_on: Vec<TerrainPredictionTransactionIdV2>,
+}
+
+/// Client-sampled terrain interaction ray.
+///
+/// Servers may use this ray to validate expressed intent, but must validate it
+/// against authoritative player/world state before accepting terrain edits.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TerrainInteractionRayV2 {
+    pub ray_origin_m: [f32; 3],
+    pub ray_dir: [f32; 3],
+    pub max_distance_m: f32,
+    pub client_view_tick: Option<u64>,
+}
+
+/// Face/contact hit semantics for Terrain Interaction Contract v2.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct TerrainInteractionHitV2 {
+    pub hit_block_pos: (i32, i32, i32),
+    pub hit_face: ClientBlockFace,
+    pub hit_point_m: Option<[f32; 3]>,
+}
+
+/// Place-specific semantics for Terrain Interaction Contract v2.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TerrainPlaceIntentV2 {
+    pub support_block_pos: (i32, i32, i32),
+    pub placement_pos: (i32, i32, i32),
+    pub block_id: BlockRuntimeId,
+    pub expected_placement_empty: bool,
+    pub expected_support_solid: bool,
+}
+
+/// Non-serialized SDK vocabulary shape for voxel terrain break/place intent v2.
+///
+/// The transport payload schema remains intentionally deferred until the owning
+/// serialized action-payload module is selected.
+#[derive(Debug, Clone, PartialEq)]
+pub struct TerrainInteractionIntentV2 {
+    pub identity: TerrainInteractionIdentityV2,
+    pub ray: TerrainInteractionRayV2,
+    pub hit: TerrainInteractionHitV2,
+    pub place: Option<TerrainPlaceIntentV2>,
+}
+
+/// Deterministic terrain interaction rejection/mismatch categories.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[non_exhaustive]
+pub enum TerrainInteractionRejectReasonV2 {
+    StaleStream,
+    DuplicateAction,
+    MissingDependency,
+    InvalidSequence,
+    InvalidCoordinates,
+    InvalidRay,
+    OutOfReach,
+    RayMismatch,
+    HitMismatch,
+    FaceMismatch,
+    Occluded,
+    TargetNotLoaded,
+    TargetNotSolid,
+    TargetNotBreakable,
+    PlacementNotLoaded,
+    PlacementNotEmpty,
+    SupportNotSolid,
+    BlockIdNotAllowed,
+    PolicyDenied,
+    StateMismatch,
+    InternalError,
+}
+
 /// One predicted block edit hint (visual-only, not authoritative).
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ClientPredictedEdit {

crates/freven_world_api/README.md

@@ -57,6 +57,11 @@ Examples:
 These are composition points over block-owned families. They do not make
 `freven_world_api` the owner of standard block gameplay semantics.
 
+Terrain break/place action payloads should follow the semantic contract in
+`../../docs/TERRAIN_INTERACTION_CONTRACT_v2.md`. `freven_world_api` owns the
+action identity/envelope fields and opaque payload carriage, not a hidden
+target-position-only validation fallback.
+
 ## Current state
 
 Stage 4.5 ownership is:

docs/GUEST_CONTRACT_v1.md

@@ -118,6 +118,11 @@ Current hosting policy:
 - `ActionResult.output` carries canonical runtime output families
 - rejected actions may carry message output, but must not carry command output
 
+Terrain break/place interactions use the long-term semantic contract in
+`TERRAIN_INTERACTION_CONTRACT_v2.md`. Contract v1 still carries action payloads
+as opaque bytes; implementations must not treat legacy target-position-only
+terrain payloads as an rc10 fallback once v2 is adopted.
+
 ## Message path
 
 - Host sends `ClientMessageInput` / `ServerMessageInput`

docs/README.md

@@ -58,6 +58,10 @@ Read them in this order:
   neutral runtime-loaded guest semantics
 - [GUEST_CONTRACT_v1.md](GUEST_CONTRACT_v1.md): canonical world-owned
   runtime-loaded guest semantics
+- [TERRAIN_INTERACTION_CONTRACT_v2.md](TERRAIN_INTERACTION_CONTRACT_v2.md):
+  long-term terrain break/place intent contract for action identity, client
+  rays, hit/place semantics, prediction, server validation, diagnostics, and
+  reconciliation
 - [MOD_CONFIG_v1.md](MOD_CONFIG_v1.md): public mod config schema,
   experience/stack authoring, resolution, and guest delivery semantics
 - [WORLDGEN_PROVIDER_CONCURRENCY_v1.md](WORLDGEN_PROVIDER_CONCURRENCY_v1.md):

docs/SDK_DISTRIBUTION.md

@@ -18,7 +18,10 @@ This repository (`frevenengine/freven-sdk`) is public-readable and contains:
 
 Reference gameplay (vanilla experience) lives in a separate repository (`frevenengine/freven-vanilla`).
 First-party gameplay helpers such as break/place payload codecs and humanoid input
-now ship from `freven-vanilla`, not from this SDK repository.
+now ship from `freven-vanilla`, not from this SDK repository. The long-term
+terrain break/place intent semantics are documented in
+`TERRAIN_INTERACTION_CONTRACT_v2.md`; legacy Vanilla payload helpers must migrate
+to that contract rather than remain an rc10 fallback.
 
 ## Publishing plan