Forge is a C# gameplay framework designed for building rich, modular game mechanics with a focus on flexibility, performance, and developer experience.
Forge's architecture is built around several interconnected systems that work together to provide a complete gameplay foundation:
At the center of Forge is the entity system, represented by IForgeEntity. Each game entity can have:
- Attributes: Numeric values that define an entity's capabilities and state.
- Tags: Labels that identify entity characteristics and enable queries.
- Effects: Gameplay effects that can modify attributes and behaviors.
- Abilities: Granted and activated gameplay abilities with instancing, costs, cooldowns, and tag requirements.
- Events: Gameplay events dispatched and listened to for triggers and reactions.
Entities serve as containers for these components, allowing for modular construction of game objects.
Attributes manage numeric values and their modifications:
- Base Values: The starting point for attribute calculations.
- Modifiers: Adjustments that affect attribute values through flat, percentage, or override operations.
- Channels: Multiple processing layers that allow for complex calculation pipelines.
- Attribute Sets: Collections of related attributes for logical organization.
Attributes can have minimum and maximum limits and support automatic recalculation when dependencies change.
Tags in Forge are lightweight identifiers that mark entities with specific characteristics:
- Tag Container: Holds and manages an entity's tags.
- Tag Queries: Allow for efficient entity selection based on tag combinations.
- Tag Requirements: Define conditions for effect application.
Tags are central to many Forge systems, enabling contextual application of effects and conditional logic.
Effects are the primary way to implement gameplay mechanics in Forge:
- Modifiers: Changes to attribute values.
- Tags: Added or removed during effect application.
- Executions: Custom logic that runs when effects are applied or removed.
- Duration: Controls how long effects remain active.
Effects can be instant or persistent, with various duration types including infinite, timed, and conditional.
Abilities manage creation and use of gameplay abilities:
- Granting: Add abilities to entities, including level scaling and ownership.
- Activation: Start ability instances with checks for inhibition and requirements.
- Costs and Cooldowns: Apply cost effects and cooldown effects via the effects system.
- Instancing Policies: Control per-entity or per-execution instances, retrigger behavior, and cancellation.
- Tag Rules: Use tags to require, block, cancel, or inhibit abilities.
Events deliver gameplay event data for triggers and reactions:
- Event Data: Structured payloads carrying source, target, and parameters.
- Tagging: Event tags for filtering and matching listeners.
- Dispatching: Raise events through entity event managers.
- Listeners and Triggers: Drive ability activation and other game logic from event hooks.
Cues bridge gameplay systems with visual and audio feedback:
- Cue Events: Triggered by gameplay events like effect application.
- Cue Parameters: Dynamic data that informs how feedback should be presented.
- Cue Handlers: Logic for converting gameplay events into sensory output.
This system keeps gameplay logic separate from presentation concerns.
Forge's architecture follows these key principles:
- Composition over Inheritance: Systems are designed to be attached to entities rather than inherited.
- Data-Driven Design: Most gameplay elements are defined as data that can be authored and modified.
- Modularity: Systems can be used independently or together based on project needs.
- Performance-Aware: Optimized for both runtime performance and memory usage.
- Deterministic: Systems prioritize predictable behavior for networking and replay support.
The framework avoids deep inheritance hierarchies, preferring flexible composition patterns that allow for greater code reuse and clearer architecture.
Forge includes a runtime validation system (Validation class) that helps catch misconfigurations and logic errors during development, editor, and testing workflows.
- By default, validation is disabled.
- Enable it by setting
Validation.Enabled = true;in your editor, test, or debug environment. - When enabled, failed validations will throw a
ValidationExceptionwith an explanatory message. - For optimal performance, leave validation disabled in production or deployment environments.
Usage Example:
Validation.Enabled = true; // Enable validation (e.g., in editor)
Validation.Assert(someCondition, "Message if failed.");For more detailed information about specific systems, refer to these documentation files:
- Attributes: Details on attribute definition, evaluation, and channels.
- Effects: Creating and applying effects to entities.
- Tags: Using the tag system for entity identification.
- Abilities: Ability granting, activation, instancing, costs, cooldowns, and tag requirements.
- Events: Event data, tagging, and trigger hooks.
- Cues: Connecting gameplay events to visual and audio feedback.
- Modifiers: How modifiers affect attribute calculations.
- Duration: Controlling how long effects remain active.
- Stacking: Configuring how multiple instances of effects combine.
- Periodic: Creating effects that execute repeatedly over time.
- Components: Extending effects with custom behaviors.
- Custom Calculators: Creating custom calculations for effects.
- Quick Start: Get up and running with Forge quickly.
To start using Forge in your project, see the Quick Start Guide for basic setup and examples of common gameplay mechanics.
For integrating Forge into your workflow, check the installation instructions and API reference in the main README file.