repository·master·Indexed 19 days ago
https://github.com/chris3606/gorogueA library providing tools for building roguelike games. Documentation includes a comprehensive upgrade guide from version 1.x to 2.0, detailing breaking changes to Coord (now a value type), the refactored GameObject and Map systems using IGameObject, updated FOV input types, and the implementation of a type-safe component system via IHasComponents and ComponentContainer.
GoRogue is a .NET Standard 2.1 library designed as a collection of tools, data structures, and algorithms for creating 2D grid-based games.
Important Distinction: GoRogue is not a full game engine. It does not provide rendering or audio capabilities. It is intended to be paired with a framework or engine that handles those aspects (e.g., SadConsole, MonoGame, Unity, Godot, or Stride).
GameFramework.Map supports a component-based architecture. You can attach components directly to a map instance via the GoRogueComponents property, similar to how you attach components to game objects. This is particularly useful when using Components.ParentAware systems.GoRogue distinguishes between two main categories of features to balance flexibility with structured development:
Core Features: Located in the root GoRogue namespace and its sub-namespaces (excluding GoRogue.GameFramework). These are generic data structures and algorithms (e.g., ISpatialMap implementations) designed to be minimally intrusive. They do not enforce a specific game architecture or data storage model, making them suitable for any game type.
Game Framework Features: Located in the GoRogue.GameFramework namespace. These features combine core features into a coherent, concrete structure. They are designed to provide a ready-to-use framework that applies to many common game use cases.
To create components that are aware of the object they are attached to, use the interfaces and classes in the GoRogue.Components.ParentAware namespace.
IObjectWithComponents: Defines a GoRogueComponents property of type IComponentCollection. Use this for objects that own a component collection.IParentAwareComponent: Specifies a Parent field of type object?.ParentAwareComponentBase: A base class that implements IParentAwareComponent and provides events for attachment/detachment.ParentAwareComponentBase<T>: A generic version that automatically casts the Parent field to type T, avoiding manual casting.When constructing a ComponentCollection, you can pass an optional object? parameter. If provided, this object is automatically assigned to the Parent field of any IParentAwareComponent added to the collection. The Parent is set to null when the component is removed.
When custom or arranged generation steps use different data formats, you can use 'translation steps' to convert data from one component type to another. These steps are located in the GoRogue.MapGeneration.Steps.Translation namespace.
For example, if one step produces an ItemList<Rectangle> and the next step requires an ItemList<Area>, you can insert a RectanglesToAreas translation step between them to ensure compatibility.
The IsStatic flag has been removed from GameObject.
In GoRogue 3, movement restrictions for terrain are enforced by the Map itself:
Map will throw an exception.This change allows for more convenient object creation via factories, as you no longer need to know the exact position at construction time to set a static flag.
GoRogue's map generation system is built on a component-based architecture using a GenerationContext. The system consists of three main pillars:
ComponentCollection to manage map data, allowing steps to add or modify components without strict schema requirements.GoRogue.MapGeneration.Steps namespace) that perform specific tasks like placing rooms or generating tunnels. A step's OnPerform method operates on a GenerationContext, reading existing components and adding or modifying others.GenerationContext and a sequence of GenerationStep objects. When generator.Generate() is called, it executes the steps in the order they were added.Note on Safety: It is recommended to use generator.ConfigAndGenerateSafe(...) instead of Generate(). This method includes exception handling for RegenerateMapException. If a step fails and indicates an invalid map state, the generator will clean the data, recreate the steps, and attempt generation again.
An EffectTrigger acts as a managed container for Effect instances. It handles the execution and automatic removal of effects based on their duration.
Add(Effect effect) to add an effect to the trigger. The effect will be executed the next time TriggerEffects() is called.TriggerEffects() to execute all currently active effects in the list. This method:Trigger() on each effect.cancelTrigger flag: if an effect sets this to true, no subsequent effects in that specific TriggerEffects() call will run.When constructing an Effect, use these constants for the duration parameter:
EffectDuration.Instant: The effect executes once and does not use the duration system.EffectDuration.Infinite: The effect stays in the EffectTrigger indefinitely until manually removed or its duration is set to 0 within its own OnTrigger implementation.EffectTrigger trigger = new EffectTrigger();
trigger.Add(new DamageEffect(monster, 10));
trigger.TriggerEffects();The effects system has been moved to the GoRogue.Effects namespace and refactored to improve performance and usability.
Effect and EffectTrigger no longer take type parameters.
Effect.Trigger and Effect.OnTrigger now use an out bool parameter. Set this to true if you want to cancel the trigger.Effect.Trigger exists that takes no parameters for instantaneous effects where cancellation is not required.EffectTrigger.TriggerEffects handles the internal boolean logic for you.If you need to pass custom parameters to an effect (the functionality provided by Effect<T> in version 2), use the new advanced classes:
AdvancedEffect<TTriggerArgs>AdvancedEffectTrigger<TTriggerArgs>These classes allow TTriggerArgs to be any type (value or reference) while maintaining the out bool cancellation mechanism.
In GoRogue 2.0, SenseSource allows for arbitrary starting intensities.
Intensity property (defaults to 1.0) determines the starting strength of the source.double value.Behavior by Source Type:
Intensity of 2.5 can pass through two cells with 1.0 resistance, but a third cell with 1.0 resistance will block it completely.Intensity. If the resistance is less than the Intensity, it does not block.ShaiRandom uses an "inner/outer" bound model rather than a "min/max" model. This allows bounds to cross, which was not permitted in Troschuetz.
If a function takes one bound, it is treated as an outer bound relative to 0:
bound > 0: Returns [0, bound)bound == 0: Returns 0bound < 0: Returns (bound, 0]If a function takes two bounds, the first is the inner and the second is the outer:
inner < outer: Returns [inner, outer)inner == outer: Returns innerinner > outer: Returns (outer, inner]Note on Inclusivity: The rules above apply to standard functions like NextInt. Functions with Inclusive or Exclusive in their name (e.g., NextInclusiveDouble) follow their own specific contracts defined in the API documentation.
In GoRogue 3, spatial maps can automatically keep an object's internal Position property in sync with the map's internal record. To use this, ensure your objects implement the IPositionable interface, which requires a Position property and specific events that fire when the position changes.
Available auto-syncing map variants:
AutoSyncSpatialMapAutoSyncMultiSpatialMapAutoSyncLayeredSpatialMapWhen using these, you can modify the Position property directly or use the spatial map's Move functions; both actions will update both the object's field and the map's record automatically.