Initial commit

Author: george-lim

.github/workflows/ci.yaml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  checks:
+    name: Run checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          components: rustfmt, clippy
+      - uses: chetan/git-restore-mtime-action@v2
+      - uses: actions-rust-lang/rustfmt@v1
+      - uses: giraffate/clippy-action@v1
+        with:
+          reporter: github-check

.gitignore

@@ -0,0 +1 @@
+/target

Cargo.lock

@@ -0,0 +1,3 @@
+[workspace]
+resolver = "2"
+members = ["crates/*"]

Cargo.toml

@@ -0,0 +1,73 @@
+# AER World
+
+AER World is a prototype game state container designed to model games like [Hearthstone](https://hearthstone.blizzard.com/en-us) and [Super Auto Pets](https://teamwood.itch.io/super-auto-pets), where entities can react to actions by spawning more actions at any point in time.
+
+## AER
+
+AER (Action Event Reaction) is a design pattern used in AER World that describes a way to clearly track and manage nested state changes caused by actions. The best way to demonstrate this is with an example.
+
+The following is an example of AER World simulating the game state as `Golem 1` attempts to move away from `Player 0`.
+
+```
+---- Player 0 ----
+life: 10/10 + 10
+position: (0, 0)
+reactions: [OpportunityAttack { damage_amount: 3 }]
+
+
+---- Golem 1 ----
+life: 2/3 + 2
+position: (0, 0)
+reactions: [Reinforce { armor_amount: 3 }]
+
+[Action] 1 -> 1 Move { to_position: (0, 1) }
+[Event] 1 -> 1 Moved { from_position: (0, 0) }
+[Reaction] 0 OpportunityAttack { damage_amount: 3 }
+        [Action] 0 -> 1 DealDamage { amount: 3 }
+        [Event] 0 -> 1 Damaged
+        [Reaction] 1 Reinforce { armor_amount: 3 }
+                [Action] 1 -> 1 GainArmor { amount: 3 }
+
+---- Golem 1 ----
+life: 1/3 + 3
+position: (0, 1)
+reactions: [Reinforce { armor_amount: 3 }]
+```
+
+1. When `Golem 1` moves away from `Player 0` as its enemy, `Player 0`'s "Opportunity Attack" reaction triggers. This interrupts the move action, and spawns a new action to deal 3 damage to the Golem.
+2. When `Golem 1` takes 3 damage, its own "Reinforce" reaction triggers. This interrupts the damage action, and spawns a new action to gain 3 armor for the Golem.
+3. Since there are no more reactions to any of the actions on the stack, the actions are popped. The golem is left with 1 HP and 3 Armor as a result of moving away from the player.
+
+The AER pattern does not permit direct mutation of systems. Instead, every possible state change must come from an **action**. An action must be performed by a source entity onto a target entity (the target can also be the source).
+
+Entity queries can be used to provide a "fuzzy search" for action targets, like AOE attacks that attack a map region as opposed to a single target.
+
+An action may mutate state multiple times, across multiple systems. For instance, dealing damage might first interact with the armor system to absorb some damage before interacting with the health system.
+
+After each system state mutation, an action may choose to emit an event based on the result having met some criteria.
+
+**Events** should only be created and used if there is a reaction that depends on it. For example, it does not make sense to create a `Death` event if there are no reactions in the world that care about death. However, it does make sense to add an event for `Move` because Opportunity Attacks may occur if an entity moves away from an enemy.
+
+**Reactions** are pre-defined event handlers, which conditionally perform more actions. They happen after an event is fired, which can happen at any point while an existing action is occuring. When a reaction occurs, it pauses the existing action and executes immediately. For example, the `Reinforce` reaction gains the reactor 3 armor whenever they are damaged.
+
+AER does not support custom runtime reactions for entities. Every reaction must already exist in the world, although you may add or remove reactions from entities during runtime as part of an action.
+
+## ECS
+
+Game world objects are represented using the [ECS](https://en.wikipedia.org/wiki/Entity_component_system) pattern. This is done for three reasons:
+
+1. **State change clarity** - when actions are performed, it becomes clear which systems are involved with the action, while not caring about what the entity actually is.
+2. **Flexible component storage** - because an entity's data is scattered across components, we are free to store the components in any way that we see fit. We could use a bidirectional map in a system for example, to efficiently query all entities in a specific position, as well as query the position of any entity. This also means that we don't have to store many variations of the same entity just to improve performance.
+3. **Powerful entity querying** - with ECS, we can making entity querying simple yet exhaustive by doing a simple set intersection for entities that have a specific component, or meet some criteria relating to the component.
+
+To keep things simple, AER World systems currently use identity hash maps to store mappings between entities and components.
+
+AER World uses [hierarchical sparse bitsets](https://github.com/tower120/hi_sparse_bitset) to perform entity queries, which provide extremely fast set intersection performance across any number of sets, at any size.
+
+## Development Flow
+
+AER World has two crates. `world` is the library for the game state container and `playground` is the simulation binary that allows you to test the public interface of `world`.
+
+Just execute `cargo run` to start the `playground` simulation.
+
+`world` will only log actions, events, and reactions to `stdout` when `debug_assertions` is enabled. The `World::describe(entity: &EntityId)` method can be used to log every component of an entity.

README.md

@@ -0,0 +1,7 @@
+[package]
+name = "playground"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+world = { path = "../world" }

crates/playground/Cargo.toml

@@ -0,0 +1,58 @@
+use world::*;
+
+fn main() {
+    let mut world = World::new();
+
+    let player = world.spawn(
+        Some(Allegiance::Player),
+        Some(Armor { current: 5 }),
+        Some(Health {
+            current: 10,
+            max: 10,
+        }),
+        Some(Position { x: 0, y: 0 }),
+        vec![Reaction::OpportunityAttack { damage_amount: 3 }],
+    );
+
+    let golem = world.spawn(
+        Some(Allegiance::Golem),
+        Some(Armor { current: 0 }),
+        Some(Health { current: 3, max: 3 }),
+        Some(Position { x: 0, y: 5 }),
+        vec![Reaction::Reinforce { armor_amount: 3 }],
+    );
+
+    world.describe(&player);
+    world.describe(&golem);
+
+    world.perform(Action::DealDamage { amount: 1 }, player, golem, 0);
+
+    let query = EntityQuery {
+        allegiance_filter: ComponentFilter::Include(&[Allegiance::Golem]),
+        position_filter: ComponentFilter::Include(&[Position { x: 0, y: 5 }]),
+    };
+
+    world.perform_with_query(Action::DealDamage { amount: 1 }, player, query, 0);
+    world.perform(Action::GainArmor { amount: 5 }, player, player, 0);
+
+    world.perform(
+        Action::Move {
+            to_position: Position { x: 0, y: 0 },
+        },
+        golem,
+        golem,
+        0,
+    );
+
+    world.perform(
+        Action::Move {
+            to_position: Position { x: 0, y: 1 },
+        },
+        golem,
+        golem,
+        0,
+    );
+
+    world.describe(&player);
+    world.describe(&golem);
+}

crates/playground/src/main.rs

@@ -0,0 +1,7 @@
+[package]
+name = "world"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+hi_sparse_bitset = "0.5"

crates/world/Cargo.toml

@@ -0,0 +1,49 @@
+use crate::{log_with_indentation, systems::components::*, EntityId, Event, World};
+
+#[cfg_attr(debug_assertions, derive(Debug))]
+#[derive(Clone, Copy)]
+pub enum Action {
+    Move { to_position: Position },
+    DealDamage { amount: i64 },
+    GainArmor { amount: i64 },
+}
+
+impl World {
+    pub fn perform(
+        &mut self,
+        action: Action,
+        source: EntityId,
+        target: EntityId,
+        stack_depth: u64,
+    ) {
+        log_with_indentation!(stack_depth, "[Action] {source:?} -> {target:?} {action:?}");
+
+        match action {
+            Action::Move { to_position } => {
+                let Some(from_position) = self.position_system.position(&target).copied() else {
+                    return;
+                };
+
+                self.position_system.move_to(target, to_position);
+
+                self.emit(Event::Moved { from_position }, source, target, stack_depth)
+            }
+            Action::DealDamage { amount } => {
+                let overflow_damage = self.armor_system.lose(&target, amount).unwrap_or(amount);
+
+                let Some(is_alive) = self.health_system.lose(&target, overflow_damage) else {
+                    return;
+                };
+
+                if overflow_damage > 0 {
+                    self.emit(Event::Damaged, source, target, stack_depth)
+                }
+
+                if !is_alive {
+                    self.destroy(&target)
+                }
+            }
+            Action::GainArmor { amount } => self.armor_system.gain(&target, amount),
+        }
+    }
+}

crates/world/src/action.rs

@@ -0,0 +1,53 @@
+use crate::{systems::components::*, utils::*, Action, EntityId, World};
+
+pub enum ComponentFilter<'qry, Component> {
+    Ignore,
+    Include(&'qry [Component]),
+    Any,
+}
+
+pub struct EntityQuery<'qry> {
+    pub allegiance_filter: ComponentFilter<'qry, Allegiance>,
+    pub position_filter: ComponentFilter<'qry, Position>,
+}
+
+impl World {
+    fn entities(&self, query: EntityQuery) -> EntitySet {
+        let allegiance_entities = match query.allegiance_filter {
+            ComponentFilter::Include(allegiances) => {
+                Some(self.allegiance_system.entities(allegiances))
+            }
+            _ => None,
+        };
+
+        let position_entities = match query.position_filter {
+            ComponentFilter::Include(positions) => Some(self.position_system.entities(positions)),
+            _ => None,
+        };
+
+        EntitySet::intersection(&[
+            match query.allegiance_filter {
+                ComponentFilter::Ignore => None,
+                ComponentFilter::Include(_) => allegiance_entities.as_ref(),
+                ComponentFilter::Any => Some(&self.allegiance_system.entities),
+            },
+            match query.position_filter {
+                ComponentFilter::Ignore => None,
+                ComponentFilter::Include(_) => position_entities.as_ref(),
+                ComponentFilter::Any => Some(&self.position_system.entities),
+            },
+        ])
+    }
+
+    pub fn perform_with_query(
+        &mut self,
+        action: Action,
+        source: EntityId,
+        query: EntityQuery,
+        stack_depth: u64,
+    ) {
+        for target in self.entities(query).iter() {
+            self.perform(action, source, target, stack_depth)
+        }
+    }
+}