[][src]Crate weasel

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.