Skip to content

README.md

Latest commit

 

History

History
152 lines (100 loc) · 7.41 KB

README.md

File metadata and controls

152 lines (100 loc) · 7.41 KB

Forge Gameplay System Documentation

Forge is a C# gameplay framework designed for building rich, modular game mechanics with a focus on flexibility, performance, and developer experience.

Core Concepts

Forge's architecture is built around several interconnected systems that work together to provide a complete gameplay foundation:

Entity System

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.

Attribute System

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.

Tag System

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.

Effect System

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.

Ability System

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.

Event System

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.

Cue System

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.

Statescript System

Statescript is a state-based scripting system for defining ability behaviors:

  • Node Graph: Graphs composed of Entry, Exit, Action, Condition, and State nodes define execution flow.
  • Hybrid Execution: Combines declarative state management with imperative message propagation.
  • Subgraphs: State nodes own downstream subgraphs, providing automatic lifetime management and cleanup.
  • Variables: Mutable graph variables and entity-level shared variables connect graph logic to runtime data.
  • Property Resolvers: Data-driven inputs from attributes, tags, comparisons, and activation context.
  • Ability Integration: Graphs plug directly into the Abilities system as IAbilityBehavior implementations.

Architecture Overview

Forge's architecture follows these key principles:

  1. Composition over Inheritance: Systems are designed to be attached to entities rather than inherited.
  2. Data-Driven Design: Most gameplay elements are defined as data that can be authored and modified.
  3. Modularity: Systems can be used independently or together based on project needs.
  4. Performance-Aware: Optimized for both runtime performance and memory usage.
  5. 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.

Validation and Debugging

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 ValidationException with 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.");

Documentation Structure

For more detailed information about specific systems, refer to these documentation files:

Core Systems

  • 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.
  • Statescript: Visual state-based scripting for ability behaviors.

Effect Features

  • 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.

Getting Started

Getting Started

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.