specs-system-macro

Many systems defined with specs are relatively mechanical in terms of what they do, and require some redundant structure. For example, a system that moves entities according to their velocity if they have not experiences a collision might look like this:

// define a type so we can implement the system for that type
struct Physics;

// provide the System impl
impl<'a> specs::System<'a> for Physics {
    // we need read access to the velocity and collision, and write access to
    // the entity's position
    type SystemData = (
        specs::ReadStorage<'a, Velocity>,
        specs::ReadStorage<'a, Collision>,
        specs::WriteStorage<'a, Position>,
    );

    // we take an instance of systemdata as the argument, which we destruct immediately
    fn run(&mut self, (velocity, collision, mut position): Self::SystemData) {
        // but then join on it to find all entities that contain velocity, collision, and position
        for (vel, col, pos) in (&velocity, &collision, &mut position).join() {
            // and run something over all of them
            if !col.has_collision {
                pos.x += vel.dx;
                pos.y += vel.dy;
            }
        }
    }
}

This macro makes defining systems like these easier: the above system can in its entirety be replaced by the macro invocation

system!{
    Physics(vel: Velocity, col: Collision, mut pos: Position) {
        if !col.has_collision {
            pos.x += vel.dx;
            pos.y += vel.dy;
        }
    }
}

The body of the "system" is executed in a loop over all the entities that implement the described components, and the presence or absence of mut dictates whether we want to use WriteStorage or ReadStorage. The end result is a unit struct Physics that already has an operationally identical System implementation.

Several systems might also require some final cleanup'code: for example, clearing the component storage for a specific component. For example, the following system uses damage.clear() after the loop in order to remove the SufferDamage component from every entity that has it:

pub struct DamageSystem;

impl<'a> System<'a> for DamageSystem {
    type SystemData = (
        WriteStorage<'a, CombatStats>,
        WriteStorage<'a, SufferDamage>,
    );

    fn run(&mut self, (mut stats, mut damage): Self::SystemData) {
        for (mut stats, damage) in (&mut stats, &damage).join() {
            stats.hp -= damage.amount;
        }
        damage.clear();
    }
}

The system! macro allows for a finally block that executes after the loop, in which the same bound names refer to the storage for the component rather than the component itself, which means the above system can be written as:

system! {
    DamageSystem (mut stats: CombatStats, mut damage: SufferDamage) {
        // damage has type SufferDamage
        stats.hp -= damage.amount;
    } finally {
        // damage has type WriteStorage<SufferDamage>
        damage.clear();
    }
}

TODO:

• Read/write access to resources
• Setup blocks in addition to finally blocks
• Systems