Class Generator
Map generator that applies a series of GenerationStep instances to a GenerationContext to generate a map.
Namespace: GoRogue.MapGeneration
Assembly: GoRogue.dll
Syntax
public class Generator : ObjectConstructors
Generator(Int32, Int32)
Creates a generator that will be used to generate a map of the given width/height.
Declaration
public Generator(int width, int height)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | width | Width of the generated map. |
| Int32 | height | Height of the generated map. |
Fields
Context
Context for the map this Generator is generating.
Declaration
public readonly GenerationContext ContextField Value
| Type | Description |
|---|---|
| GenerationContext |
Properties
GenerationSteps
Steps used to generate the map.
Declaration
public IReadOnlyList<GenerationStep> GenerationSteps { get; }Property Value
| Type | Description |
|---|---|
| IReadOnlyList<GenerationStep> |
Methods
AddComponent(Object, String)
Adds a component to the context this generator is applying generation steps to.
Declaration
public Generator AddComponent(object component, string tag = null)Parameters
| Type | Name | Description |
|---|---|---|
| Object | component | Component to add to the map context. |
| String | tag | An optional tag to give the component. Defaults to no tag. |
Returns
| Type | Description |
|---|---|
| Generator | This generator (for chaining). |
AddStep(GenerationStep)
Adds a generation step. Steps are executed in the order they are added.
Declaration
public Generator AddStep(GenerationStep step)Parameters
| Type | Name | Description |
|---|---|---|
| GenerationStep | step | The generation step to add. |
Returns
| Type | Description |
|---|---|
| Generator | This generator (for chaining). |
AddSteps(GenerationStep[])
Adds the given generation steps. Steps are executed in the order they are added.
Declaration
public Generator AddSteps(params GenerationStep[] steps)Parameters
| Type | Name | Description |
|---|---|---|
| GenerationStep[] | steps | The generation steps to add. |
Returns
| Type | Description |
|---|---|
| Generator | This generator (for chaining). |
AddSteps(IEnumerable<GenerationStep>)
Adds the given generation steps. Steps are executed in the order they are added.
Declaration
public Generator AddSteps(IEnumerable<GenerationStep> steps)Parameters
| Type | Name | Description |
|---|---|---|
| IEnumerable<GenerationStep> | steps | The generation steps to add. |
Returns
| Type | Description |
|---|---|
| Generator | This generator (for chaining). |
Clear()
Clears the context and generation steps, resetting the generator back to a pre-configured state.
Declaration
public void Clear()ConfigAndGenerateSafe(Action<Generator>, Int32)
Calls the generatorConfig function to add components/steps to the generator, then calls
Generate(). If a RegenerateMapException is thrown, re-generates the map by
calling the configure function then generate again, up to the maximum retries specified.
Declaration
public Generator ConfigAndGenerateSafe(Action<Generator> generatorConfig, int maxAttempts = -1)Parameters
| Type | Name | Description |
|---|---|---|
| Action<Generator> | generatorConfig | Function to configure the generator. |
| Int32 | maxAttempts | Maximum times to attempt map generation, before throwing a MapGenerationFailed exception. Defaults to infinite. |
Returns
| Type | Description |
|---|---|
| Generator | This generator (for chaining). |
Remarks
This is a safe wrapper to work with generation procedures that can get themselves into an invalid state that requires re-generating the entire map. Generation steps are clearly marked in documentation if they can produce such states.
Ensure you do NOT create/use an RNG with a static seed within this function, as it could easily create an infinite loop (that would re-generate the same invalid map over and over).
ConfigAndGetStageEnumeratorSafe(Action<Generator>, Int32)
Calls the generatorConfig function to add components/steps to the generator, then calls
GetStageEnumerator() and evaluates its enumerator, returning at each step. Restarts map
generation automatically if RegenerateMapException is thrown. Typically you will want
to use ConfigAndGenerateSafe(Action<Generator>, Int32) instead.
Declaration
public IEnumerator<object> ConfigAndGetStageEnumeratorSafe(Action<Generator> generatorConfig, int maxAttempts = -1)Parameters
| Type | Name | Description |
|---|---|---|
| Action<Generator> | generatorConfig | Function to configure the generator. |
| Int32 | maxAttempts | Maximum times to attempt map generation, before throwing a MapGenerationFailed exception. Defaults to infinite. |
Returns
| Type | Description |
|---|---|
| IEnumerator<Object> | An enumerator that will complete a stage of the generation step each time its MoveNext function is called. |
Remarks
For traditional cases, you will want to call the ConfigAndGenerateSafe(Action<Generator>, Int32) function which takes the same parameters and simply completes all steps. However, if you want to visually examine each stage of the generation algorithm, you can call this function, then call the resulting enumerator's MoveNext function each time you want to complete a stage. This can be useful for demonstration purposes and debugging.
Generate()
Applies the generation steps added, in the order in which they were added, to the Context to generate the map. If you want to automatically handle RegenerateMapException, call ConfigAndGenerateSafe(Action<Generator>, Int32) instead.
Declaration
public Generator Generate()Returns
| Type | Description |
|---|---|
| Generator | This generator (for chaining). |
Remarks
Depending on the generation steps used, this function may throw RegenerateMapException if it detects that the map generated does not meet invariants due to RNG, in which case the map generation will need to be performed again. See ConfigAndGenerateSafe(Action<Generator>, Int32) for a method of ensuring this happens in a convenient way.
GetStageEnumerator()
Returns an enumerator that, when evaluated to completion, performs each stage sequentially (as defined by the generation steps in their implementation); one stage per MoveNext call. Typically you will want to use Generate() instead. If you want to automatically handle RegenerateMapException, call ConfigAndGetStageEnumeratorSafe(Action<Generator>, Int32) or ConfigAndGenerateSafe(Action<Generator>, Int32) instead as applicable.
Declaration
public IEnumerator<object> GetStageEnumerator()Returns
| Type | Description |
|---|---|
| IEnumerator<Object> | An enumerator that will complete a stage of the generation step each time its MoveNext function is called. |
Remarks
For traditional cases, you will want to call the Generate() function which simply completes all steps. However, if you want to visually examine each stage of the generation algorithm, you can call this function, then call the resulting enumerator's MoveNext function each time you want to complete a stage. This can be useful for demonstration purposes and debugging.
Note that a RegenerateMapException may be raised during this iteration, and it must be handled manually. See ConfigAndGetStageEnumeratorSafe(Action<Generator>, Int32) for a method of handling this automatically.