Crate weasel

Expand description

weasel is a customizable battle system for turn-based games.

Simple way to define the combat’s rules, taking advantage of Rust’s strong type system.
Battle events are collected into a timeline to support save and restore, replays, and more.
Client/server architecture; all battle events are verified by the server.
Minimal performance overhead.

§Examples

use weasel::{
    battle_rules, rules::empty::*, Battle, BattleController,
    BattleRules, CreateTeam, EventTrigger, Server,
};

battle_rules! {}

let battle = Battle::builder(CustomRules::new()).build();
let mut server = Server::builder(battle).build();

CreateTeam::trigger(&mut server, 1).fire().unwrap();
assert_eq!(server.battle().entities().teams().count(), 1);

You can find real examples of battle systems made with weasel in examples.

§How does it work?

To use this library, you would create instances of its main objects: server and client. You will notice that both of them are parameterized with a BattleRules generic type.
A server is mandatory to manage a game. A server can be also a client. For example, a typical single player game needs only one server.
A client is a participant to a game. It sends commands to a server on behalf of a player. A multiplayer game would have one server and multiple clients.

Once you have instantiated a server and possibly one or more clients, you are ready to begin a new game.
Games are carried forward by creating events. There are many kind of events, see the documentation to know more.

Through a server or a client you’ll be able to access the full state of the battle, including the entire timeline of events.

§Features

weasel provides many functionalities to ease the development of a turn based game:

Creatures and inanimate objects.
Statistics and abilities for characters.
Long lasting status effects.
Player managed teams.
Team objectives and diplomacy.
Division of the battle into turns and rounds.
Rules to govern the game subdivided into orthogonal traits.
Fully serializable battle history.
Cause-effect relationship between events.
Server side verification of clients’ events.
Player permissions and authorization.
Versioning for battle rules.
User defined events.
System and user defined metrics.
Sinks to forward events to an arbitrary destination.
Small collection of predefined rules.

§Define the game’s rules via traits

BattleRules is a collection of modules and it lets you define all the rules for your game by implementing a trait for each module.
Having multiple modules helps you in decomposing your rules into smaller parts, orthogonal to each other.

§Predefined rules traits

weasel contains a minimal set of predefined rules traits, mainly comprised of rules that do nothing and of basic rules for entropy.

You can find the predefined rules in the ::rules scope.

§Event based

weasel is fully based on events. It means that all changes on the battle state must be done through events.
Thanks to this strong restriction, the library can collect all events into a historical timeline. This timeline can then be exported and re-imported at a later stage; this’s fundamental to implement save and load or even replays.

Users can register on a callback each time an event is processed, to extend the library’s functionalities with their own logic.

It’s possible to create your own events, by implementing the Event trait and using the reserved EventKind::UserEvent. Remember to also write a UserEventPacker in the case you wish to enable serialization.

§Client - server architecture

The library uses a client - server architecture to support multiplayer games. Both server and clients contain a replica of the battle’s state, but only the events verified by the server will be able to change the state. Client late connection and reconnection are supported.

It is necessary that all peers use the same version of the rules.

§Metrics

There’s a built-in storage for metrics that let you retrieve and modify individual metrics based on an unique id. Metrics are divided in two kind: system and user defined.

System metrics are predefined and handled by the library. You can only read their current value.

User defined metrics can be created on the fly. The user has full power over them: they can be removed, modified and read.

§Optional Features

The following optional features are available:

random: enables built-in entropy rules that use a pseudorandom number generator.
serialization: enables serialization and deserialization of events.

Re-exports§

pub use crate::ability::ActivateAbility;
pub use crate::actor::Action;
pub use crate::actor::Actor;
pub use crate::actor::ActorRules;
pub use crate::actor::AlterAbilities;
pub use crate::actor::RegenerateAbilities;
pub use crate::battle::Battle;
pub use crate::battle::BattleController;
pub use crate::battle::BattleRules;
pub use crate::battle::BattleState;
pub use crate::battle::EndBattle;
pub use crate::battle::EventCallback;
pub use crate::battle::Version;
pub use crate::character::AlterStatistics;
pub use crate::character::Character;
pub use crate::character::CharacterRules;
pub use crate::character::RegenerateStatistics;
pub use crate::client::Client;
pub use crate::creature::ConvertCreature;
pub use crate::creature::CreateCreature;
pub use crate::creature::Creature;
pub use crate::creature::RemoveCreature;
pub use crate::entity::Entities;
pub use crate::entity::Entity;
pub use crate::entity::EntityId;
pub use crate::entity::RemoveEntity;
pub use crate::entity::Transmutation;
pub use crate::entropy::Entropy;
pub use crate::entropy::EntropyRules;
pub use crate::entropy::ResetEntropy;
pub use crate::error::WeaselError;
pub use crate::error::WeaselResult;
pub use crate::event::ClientEventPrototype;
pub use crate::event::Event;
pub use crate::event::EventId;
pub use crate::event::EventKind;
pub use crate::event::EventProcessor;
pub use crate::event::EventPrototype;
pub use crate::event::EventQueue;
pub use crate::event::EventReceiver;
pub use crate::event::EventRights;
pub use crate::event::EventServer;
pub use crate::event::EventTrigger;
pub use crate::event::EventWrapper;
pub use crate::event::LinkedQueue;
pub use crate::event::VersionedEventWrapper;
pub use crate::fight::ApplyImpact;
pub use crate::fight::FightRules;
pub use crate::history::History;
pub use crate::metric::Metric;
pub use crate::metric::MetricId;
pub use crate::metric::ReadMetrics;
pub use crate::metric::SystemMetricId;
pub use crate::metric::WriteMetrics;
pub use crate::object::CreateObject;
pub use crate::object::Object;
pub use crate::object::RemoveObject;
pub use crate::player::PlayerId;
pub use crate::power::InvokePower;
pub use crate::round::EndRound;
pub use crate::round::EndTurn;
pub use crate::round::EnvironmentTurn;
pub use crate::round::ResetRounds;
pub use crate::round::Rounds;
pub use crate::round::RoundsRules;
pub use crate::round::StartTurn;
pub use crate::serde::FlatClientEvent;
pub use crate::serde::FlatEvent;
pub use crate::serde::FlatVersionedEvent;
pub use crate::server::Server;
pub use crate::space::AlterSpace;
pub use crate::space::MoveEntity;
pub use crate::space::PositionClaim;
pub use crate::space::ResetSpace;
pub use crate::space::Space;
pub use crate::space::SpaceRules;
pub use crate::status::AlterStatuses;
pub use crate::status::Application;
pub use crate::status::AppliedStatus;
pub use crate::status::ClearStatus;
pub use crate::status::InflictStatus;
pub use crate::team::AlterPowers;
pub use crate::team::Call;
pub use crate::team::ConcludeObjectives;
pub use crate::team::Conclusion;
pub use crate::team::CreateTeam;
pub use crate::team::EntityAddition;
pub use crate::team::RegeneratePowers;
pub use crate::team::Relation;
pub use crate::team::RemoveTeam;
pub use crate::team::ResetObjectives;
pub use crate::team::SetRelations;
pub use crate::team::Team;
pub use crate::team::TeamRules;
pub use crate::user::UserEventPacker;
pub use crate::user::UserEventId;
pub use crate::user::UserRules;
pub use crate::util::Id;

Modules§

ability: Module to manage abilities.
actor: Entities that can activate abilities.
battle: Battle module.
character: Character rules.
client: A battle client.
creature: Main entity in the game.
entity: Module for entities and their storage.
entropy: Randomness model.
error: Error and Result module.
event: Event module.
fight: Module to handle combat.
history: History of events.
metric: Metrics for battles.
object: Inanimate objects.
player: Player-oriented features.
power: Module to manage powers.
round: Everything related to the battle’s turns and rounds.
rules: Collection of generic rules.
serde: Module to handle serialization and deserialization.
server: A battle server.
space: Module for the spatial dimension.
status: Module for long lasting status effects.
team: Teams of entities.
user: User defined extension for battle rules functionalities.
util: Collection of utilities.

Macros§

battle_rules: Macro to quickly generate battle rules.
battle_rules_with_actor: Empty battle rules with user defined ActorRules.
battle_rules_with_character: Empty battle rules with user defined CharacterRules.
battle_rules_with_entropy: Empty battle rules with user defined EntropyRules.
battle_rules_with_fight: Empty battle rules with user defined FightRules.
battle_rules_with_rounds: Empty battle rules with user defined RoundsRules.
battle_rules_with_space: Empty battle rules with user defined SpaceRules.
battle_rules_with_team: Empty battle rules with user defined TeamRules.
battle_rules_with_user: Empty battle rules with user defined UserRules.

Crate weaselCopy item path