tiny.sdfii.internals.command.sink

1pub const sink = @import("sink.zig");

1const std = @import("std");2const ecs = @import("sdfii_ecs");3const sdfii_world = @import("sdfii_world");45const WorldStore = sdfii_world.store;6const Commands = sdfii_world.commands;7const Schema = sdfii_world.schema;89const Self = @This();1011pub const EntityId = ecs.EntityId;12pub const TransformDesc = ecs.SdfiiTransformDesc;13pub const physics_component_schema_id: u64 = @backingInt(Schema.ComponentSchema.physics);1415pub const SpawnSpec = struct {16    name: ?[]const u8 = null,17    key: ?[]const u8 = null,18    transform: ?TransformDesc = null,19};2021pub const PhysicsBlobSpec = struct {22    entity: EntityId,23    payload: []const u8,24};2526pub const TransformSpec = struct {27    entity: EntityId,28    transform: TransformDesc,29};3031pub const EventSpec = struct {32    schema_id: u64,33    payload: []const u8 = &.{},34};3536pub const Command = union(enum) {37    spawn: SpawnSpec,38    despawn: EntityId,39    attach_physics_blob: PhysicsBlobSpec,40    set_transform: TransformSpec,41    emit: EventSpec,42};4344pub const CommandKind = enum(u8) {45    spawn = 1,46    despawn = 2,47    attach_physics = 3,48    set_transform = 4,49    emit = 5,50};5152pub const Error = error{53    BatchTooLarge,54    InvalidUtf8,55    SpawnBufferTooSmall,56    SubmitFailed,57    OutOfMemory,58};5960pub const BatchResult = struct {61    command_count: u32,62    spawned_count: u32,63};6465pub const SpawnResult = struct {66    entity: EntityId,67    command_count: u32,68};6970pub const SpawnManyResult = struct {71    count: usize,72    command_count: u32,73};7475pub const MutationResult = struct {76    command_count: u32,77};7879pub const EventResult = struct {80    command_count: u32,81    visible_event_count: usize,82};8384pub const ApplyResult = struct {85    command_count: usize,86    spawned_count: usize,87    event_count: usize,88    visible_event_count: usize,89};9091allocator: std.mem.Allocator,92world: *WorldStore,9394pub fn bind(allocator: std.mem.Allocator, world: *WorldStore) Self {95    return .{96        .allocator = allocator,97        .world = world,98    };99}100101pub fn submitBatch(self: *const Self, batch: *Commands.Batch, spawned_ids: ?[]EntityId) Error!BatchResult {102    const command_count = batch.count();103    const spawned_count = self.world.submit(batch, spawned_ids) catch |err| return mapError(err);104    return .{105        .command_count = command_count,106        .spawned_count = spawned_count,107    };108}109110pub fn spawn(self: *const Self, spec: SpawnSpec) Error!SpawnResult {111    var batch = try Commands.Batch.init(self.allocator, 4);112    defer batch.deinit();113114    try batch.pushSpawn(spec.name, spec.key, spec.transform);115116    var spawned: [1]EntityId = .{.{ .index = std.math.maxInt(u32), .generation = 0 }};117    const result = try self.submitBatch(&batch, spawned[0..]);118    std.debug.assert(result.spawned_count == 1);119    return .{120        .entity = spawned[0],121        .command_count = result.command_count,122    };123}124125pub fn spawnMany(self: *const Self, specs: []const SpawnSpec, out: []EntityId) Error!SpawnManyResult {126    if (out.len < specs.len) return error.SpawnBufferTooSmall;127    if (specs.len == 0) return .{ .count = 0, .command_count = 0 };128129    const capacity_hint: u32 = std.math.cast(u32, specs.len) orelse return error.BatchTooLarge;130    var batch = try Commands.Batch.init(self.allocator, @max(capacity_hint, @as(u32, 4)));131    defer batch.deinit();132133    for (specs) |spec| {134        try batch.pushSpawn(spec.name, spec.key, spec.transform);135    }136137    const result = try self.submitBatch(&batch, out[0..specs.len]);138    const spawned_count: usize = @intCast(result.spawned_count);139    std.debug.assert(spawned_count == specs.len);140    return .{141        .count = spawned_count,142        .command_count = result.command_count,143    };144}145146pub fn despawn(self: *const Self, entity: EntityId) Error!MutationResult {147    var batch = try Commands.Batch.init(self.allocator, 4);148    defer batch.deinit();149    try batch.pushDespawn(entity);150    const result = try self.submitBatch(&batch, null);151    return .{ .command_count = result.command_count };152}153154pub fn attachPhysicsBlob(self: *const Self, entity: EntityId, payload: []const u8) Error!MutationResult {155    var batch = try Commands.Batch.init(self.allocator, 4);156    defer batch.deinit();157    try batch.pushUpsertComponent(entity, physics_component_schema_id, payload);158    const result = try self.submitBatch(&batch, null);159    return .{ .command_count = result.command_count };160}161162pub fn setTransform(self: *const Self, entity: EntityId, transform: TransformDesc) Error!MutationResult {163    var batch = try Commands.Batch.init(self.allocator, 4);164    defer batch.deinit();165    try batch.pushSetTransform(entity, transform);166    const result = try self.submitBatch(&batch, null);167    return .{ .command_count = result.command_count };168}169170pub fn emit(self: *const Self, schema_id: u64, payload: []const u8) Error!EventResult {171    var batch = try Commands.Batch.init(self.allocator, 4);172    defer batch.deinit();173    try batch.pushEnqueueEvent(schema_id, payload);174    try batch.pushPublishEvents();175    const result = try self.submitBatch(&batch, null);176    return .{177        .command_count = result.command_count,178        .visible_event_count = self.world.visibleEventCount(),179    };180}181182pub fn applyCommands(183    self: *const Self,184    commands: []const Command,185    spawned_out: []EntityId,186) Error!ApplyResult {187    var expected_spawn_count: usize = 0;188    var event_count: usize = 0;189    for (commands) |command| {190        switch (command) {191            .spawn => expected_spawn_count += 1,192            .emit => event_count += 1,193            .despawn, .attach_physics_blob, .set_transform => {},194        }195    }196    if (spawned_out.len < expected_spawn_count) return error.SpawnBufferTooSmall;197    if (commands.len == 0) return .{198        .command_count = 0,199        .spawned_count = 0,200        .event_count = 0,201        .visible_event_count = self.world.visibleEventCount(),202    };203204    const internal_count = std.math.add(usize, commands.len, @intFromBool(event_count != 0)) catch205        return error.BatchTooLarge;206    const capacity_hint = std.math.cast(u32, internal_count) orelse return error.BatchTooLarge;207    var batch = try Commands.Batch.init(self.allocator, @max(capacity_hint, @as(u32, 4)));208    defer batch.deinit();209210    for (commands) |command| {211        switch (command) {212            .spawn => |spec| try batch.pushSpawn(spec.name, spec.key, spec.transform),213            .despawn => |entity| try batch.pushDespawn(entity),214            .attach_physics_blob => |spec| try batch.pushUpsertComponent(215                spec.entity,216                physics_component_schema_id,217                spec.payload,218            ),219            .set_transform => |spec| try batch.pushSetTransform(spec.entity, spec.transform),220            .emit => |spec| try batch.pushEnqueueEvent(spec.schema_id, spec.payload),221        }222    }223    if (event_count != 0) try batch.pushPublishEvents();224225    const result = try self.submitBatch(&batch, spawned_out[0..expected_spawn_count]);226    const spawned_count: usize = @intCast(result.spawned_count);227    std.debug.assert(spawned_count == expected_spawn_count);228    return .{229        .command_count = commands.len,230        .spawned_count = spawned_count,231        .event_count = event_count,232        .visible_event_count = self.world.visibleEventCount(),233    };234}235236fn mapError(err: anyerror) Error {237    return switch (err) {238        error.OutOfMemory => error.OutOfMemory,239        error.InvalidUtf8 => error.InvalidUtf8,240        error.SpawnBufferTooSmall => error.SpawnBufferTooSmall,241        error.BatchTooLarge => error.BatchTooLarge,242        else => error.SubmitFailed,243    };244}245246test "direct command sink spawns and updates engine-owned storage" {247    const allocator = std.testing.allocator;248    var world = try WorldStore.init(allocator, 8);249    defer world.deinit();250    world.markEngineOwned();251252    const sink = Self.bind(allocator, &world);253    const spawned = try sink.spawn(.{254        .name = "player",255        .key = "hero",256        .transform = .{ .pos_x = 1, .pos_y = 2, .pos_z = 3 },257    });258259    try std.testing.expectEqual(@as(u32, 1), spawned.command_count);260    try std.testing.expect(world.isAlive(spawned.entity));261    const updated = try sink.setTransform(spawned.entity, .{ .pos_x = 4, .pos_y = 5, .pos_z = 6 });262    try std.testing.expectEqual(@as(u32, 1), updated.command_count);263264    const stored = world.transformDesc(spawned.entity).?;265    try std.testing.expectEqual(@as(f32, 4), stored.pos_x);266    try std.testing.expectEqual(@as(f32, 5), stored.pos_y);267    try std.testing.expectEqual(@as(f32, 6), stored.pos_z);268}269270test "direct command sink preserves batch ordering" {271    const allocator = std.testing.allocator;272    var world = try WorldStore.init(allocator, 8);273    defer world.deinit();274    world.markEngineOwned();275276    const sink = Self.bind(allocator, &world);277    const specs = [_]SpawnSpec{278        .{ .name = "a", .transform = .{ .pos_x = 1 } },279        .{ .key = "b" },280        .{ .name = "c", .transform = .{ .pos_z = 3 } },281    };282    var out: [3]EntityId = undefined;283284    const result = try sink.spawnMany(&specs, &out);285    try std.testing.expectEqual(@as(usize, 3), result.count);286    try std.testing.expectEqual(@as(u32, 3), result.command_count);287    for (out) |entity| {288        try std.testing.expect(world.isAlive(entity));289    }290291    try std.testing.expectEqual(@as(f32, 1), world.transformDesc(out[0]).?.pos_x);292    try std.testing.expect(world.transformDesc(out[1]) == null);293    try std.testing.expectEqual(@as(f32, 3), world.transformDesc(out[2]).?.pos_z);294}295296test "spawn many rejects a late invalid spec without touching world or output" {297    const allocator = std.testing.allocator;298    var world = try WorldStore.init(allocator, 8);299    defer world.deinit();300    world.markEngineOwned();301302    const sink = Self.bind(allocator, &world);303    const invalid_utf8 = [_]u8{0xff};304    const specs = [_]SpawnSpec{305        .{ .name = "valid" },306        .{ .name = &invalid_utf8 },307    };308    const sentinel = EntityId{ .index = std.math.maxInt(u32), .generation = std.math.maxInt(u32) };309    var out: [2]EntityId = .{ sentinel, sentinel };310311    try std.testing.expectError(error.InvalidUtf8, sink.spawnMany(&specs, &out));312    try std.testing.expectEqual(@as(u32, 0), world.aliveCount());313    try std.testing.expectEqual(sentinel, out[0]);314    try std.testing.expectEqual(sentinel, out[1]);315}316317test "typed command list reports spawned and emitted commands" {318    const allocator = std.testing.allocator;319    var world = try WorldStore.init(allocator, 8);320    defer world.deinit();321    world.markEngineOwned();322323    const sink = Self.bind(allocator, &world);324    const commands = [_]Command{325        .{ .spawn = .{ .name = "a" } },326        .{ .emit = .{ .schema_id = 9, .payload = "evt" } },327    };328    var spawned: [1]EntityId = undefined;329330    const result = try sink.applyCommands(&commands, &spawned);331    try std.testing.expectEqual(@as(usize, 2), result.command_count);332    try std.testing.expectEqual(@as(usize, 1), result.spawned_count);333    try std.testing.expectEqual(@as(usize, 1), result.event_count);334    try std.testing.expect(world.isAlive(spawned[0]));335    try std.testing.expectEqual(@as(usize, 1), world.visibleEventCount());336}337338test "typed command list commits atomically and publishes all emitted events" {339    const allocator = std.testing.allocator;340    var world = try WorldStore.init(allocator, 8);341    defer world.deinit();342    world.markEngineOwned();343344    const sink = Self.bind(allocator, &world);345    const invalid_utf8 = [_]u8{0xff};346    const rejected = [_]Command{347        .{ .spawn = .{ .name = "would-commit-first" } },348        .{ .spawn = .{ .name = &invalid_utf8 } },349    };350    const rejected_sentinel = EntityId{351        .index = std.math.maxInt(u32),352        .generation = std.math.maxInt(u32),353    };354    var rejected_spawns: [2]EntityId = .{ rejected_sentinel, rejected_sentinel };355    try std.testing.expectError(error.InvalidUtf8, sink.applyCommands(&rejected, &rejected_spawns));356    try std.testing.expectEqual(@as(u32, 0), world.aliveCount());357    try std.testing.expectEqual(rejected_sentinel, rejected_spawns[0]);358    try std.testing.expectEqual(rejected_sentinel, rejected_spawns[1]);359360    const accepted = [_]Command{361        .{ .emit = .{ .schema_id = 7, .payload = "first" } },362        .{ .emit = .{ .schema_id = 8, .payload = "second" } },363    };364    var no_spawns: [0]EntityId = .{};365    const result = try sink.applyCommands(&accepted, &no_spawns);366    try std.testing.expectEqual(@as(usize, 2), result.event_count);367    try std.testing.expectEqual(@as(usize, 2), result.visible_event_count);368    try std.testing.expectEqual(@as(u64, 7), world.visibleEvent(0).?.schema_id);369    try std.testing.expectEqual(@as(u64, 8), world.visibleEvent(1).?.schema_id);370}371372test "typed command list rolls back every allocation failure and retries" {373    var saw_operation_failure = false;374    var completed_sweep = false;375    for (0..512) |fail_index| {376        var failing = std.testing.FailingAllocator.init(std.testing.allocator, .{ .fail_index = fail_index });377        var world = WorldStore.init(failing.allocator(), 2) catch |err| {378            try std.testing.expectEqual(error.OutOfMemory, err);379            try std.testing.expectEqual(failing.allocated_bytes, failing.freed_bytes);380            continue;381        };382        const existing = world.entities.spawn() catch |err| {383            try std.testing.expectEqual(error.OutOfMemory, err);384            world.deinit();385            try std.testing.expectEqual(failing.allocated_bytes, failing.freed_bytes);386            continue;387        };388        world.transforms.insert(existing.index, .{ .pos_x = 1 }) catch |err| {389            try std.testing.expectEqual(error.OutOfMemory, err);390            world.deinit();391            try std.testing.expectEqual(failing.allocated_bytes, failing.freed_bytes);392            continue;393        };394        world.markEngineOwned();395396        const sink = Self.bind(failing.allocator(), &world);397        const commands = [_]Command{398            .{ .set_transform = .{ .entity = existing, .transform = .{ .pos_x = 9 } } },399            .{ .emit = .{ .schema_id = 42, .payload = "event" } },400            .{ .spawn = .{ .name = "spawned", .transform = .{ .pos_z = 3 } } },401        };402        const sentinel = EntityId{ .index = std.math.maxInt(u32), .generation = std.math.maxInt(u32) };403        var spawned: [1]EntityId = .{sentinel};404405        const attempt = sink.applyCommands(&commands, &spawned);406        if (attempt) |result| {407            try std.testing.expect(!failing.has_induced_failure);408            try expectMixedBatchResult(&world, existing, spawned[0], result);409            completed_sweep = true;410        } else |err| {411            try std.testing.expectEqual(error.OutOfMemory, err);412            try std.testing.expect(failing.has_induced_failure);413            saw_operation_failure = true;414            try std.testing.expectEqual(@as(u32, 1), world.aliveCount());415            try std.testing.expectEqual(@as(f32, 1), world.transformDesc(existing).?.pos_x);416            try std.testing.expectEqual(@as(usize, 0), world.visibleEventCount());417            try std.testing.expectEqual(@as(usize, 0), world.pendingEventCount());418            try std.testing.expectEqual(sentinel, spawned[0]);419420            failing.fail_index = std.math.maxInt(usize);421            failing.resize_fail_index = std.math.maxInt(usize);422            const result = try sink.applyCommands(&commands, &spawned);423            try expectMixedBatchResult(&world, existing, spawned[0], result);424        }425426        world.deinit();427        try std.testing.expectEqual(failing.allocated_bytes, failing.freed_bytes);428        if (completed_sweep) break;429    }430    try std.testing.expect(saw_operation_failure);431    try std.testing.expect(completed_sweep);432}433434fn expectMixedBatchResult(435    world: *const WorldStore,436    existing: EntityId,437    spawned: EntityId,438    result: ApplyResult,439) !void {440    try std.testing.expectEqual(@as(usize, 3), result.command_count);441    try std.testing.expectEqual(@as(usize, 1), result.spawned_count);442    try std.testing.expectEqual(@as(usize, 1), result.event_count);443    try std.testing.expectEqual(@as(usize, 1), result.visible_event_count);444    try std.testing.expectEqual(@as(u32, 2), world.aliveCount());445    try std.testing.expectEqual(@as(f32, 9), world.transformDesc(existing).?.pos_x);446    try std.testing.expect(world.isAlive(spawned));447    try std.testing.expectEqual(@as(f32, 3), world.transformDesc(spawned).?.pos_z);448    try std.testing.expectEqual(@as(u64, 42), world.visibleEvent(0).?.schema_id);449}