Merge branch 'master' of github.com:npruehs/ByChance

README.md

@@ -4,6 +4,32 @@ ByChance
 The ByChance Framework allows game developers to provide an infinite amount of unique levels for both 2D and 3D games. Easy to integrate into video games of all genres, ByChance enables you to generate complex levels including all of their game components and comes with useful post-processing algorithms that can be applied afterwards in order to ensure a great gaming experience.
 
 
+## Contents
+
+1. [Getting Started](#getting-started)
+	1. [Getting ByChance Binaries](#getting-bychance-binaries)
+	2. [Getting ByChance Sources](#getting-bychance-sources)
+2. [Generating Your First Level](#generating-your-first-level)
+3. [Customizing the Chunk Library](#customizing-the-chunk-library)
+	1. [Weights and Tags](#weights-and-tags)
+	2. [Anchors](#anchors)
+	3. [Chunk Rotations](#chunk-rotations)
+4. [Configuring the Level Generator](#configuring-the-level-generator)
+	1. [Restricting Context Alignment](#restricting-context-alignment)
+	2. [Modifying Effective Chunk Weights](#modifying-effective-chunk-weights)
+	3. [Post-processing](#post-processing)
+		1. [Aligning Adjacent Contexts](#aligning-adjacent-contexts)
+		2. [Discarding Open Chunks](#discarding-open-chunks)
+		3. [Discarding Open Contexts](#discarding-open-contexts)
+		4. [Creating Custom Post-Processing Policies](#creating-custom-post-processing-policies)
+5. [Adapting the Level Generation Process](#adapting-the-level-generation-process)
+	1. [Setting The First Level Chunk](#setting-the-first-level-chunk)
+	2. [Using Level Generator Seeds](#using-level-generator-seeds)
+6. [Logging with the ByChance Framework](#logging-with-the-bychance-framework)
+7. [Best Practice](#best-practice)
+	1. [Chunk Size](#chunk-size)
+8. [Next Steps](#next-steps)
+
 ## Getting Started
 
 The core of the ByChance Framework is a generic level generation algorithm that is able to construct 2D and 3D levels alike. Thus, you only need to understand the framework fundamentals once, and will then be able to create levels for games of all genres.
@@ -125,6 +151,30 @@ public class DoorContextAlignmentRestriction : IContextAlignmentRestriction
 levelGenerator.Configuration.ContextAlignmentRestriction = new DoorContextAlignmentRestriction();
 ```
 
+### Modifying Effective Chunk Weights
+
+As we know, every chunk has a relative weight that tells the level generator how often a specific chunk should be added to the level. However, the level generator takes account which contexts these chunks are added at. You can override the weight of a chunk template with respect to the context that is aligned at by providing your own implementation of IChunkDistribution:
+
+```csharp
+public class SealedDoorDistribution : IChunkDistribution
+{
+    public int GetEffectiveWeight(Context firstContext, Context secondContext, int occurrences)
+    {
+        if (firstContext.Tag.Equals("Door") && secondContext.Tag.Equals("SealedDoor"))
+        {
+            return secondContext.Source.Weight / (occurrences + 1);
+        }
+
+        // Default implementation.
+        return secondContext.Source.Weight;
+    }
+}
+```
+
+```csharp
+levelGenerator.Configuration.ChunkDistribution = new SealedDoorDistribution();
+```
+
 ### Post-processing
 
 Since it is the nature of the level generation algorithm to fill out the level boundaries as much as possible, the resulting level often shows unwanted patterns. A typical example is a corridor that leads nowhere. To avoid this, some kind of post-processing is required after the level has been generated.
@@ -263,6 +313,12 @@ levelGenerator.Configuration.Logger = new UnityLevelGenerationLogger();
 
 The framework uses NLog for writing verbose log output to a file next to the binary of your game called ByChance.log. You can change the logging behaviour in the configuration file NLog.config.
 
+## Best Practice
+
+### Chunk Size
+
+Clearly, the level generation time increases with the number of chunks that are placed. Thus, given a fixed level size, you'll want to use chunks that are bigger than you smallest level unit. For example, if you're generating a map that consists of 128 x 128 tiles, you'll want to define chunks that are bigger that one tile in size.
+
 ## Next Steps
 
 You’ve learned how to integrate the ByChance Framework into your game and how to have the level generator create random levels the way you want them to be. Feel free to take a look at the [API documentation](http://www.levelsbychance.com/api/Index.html) for detailed descriptions of how everything’s tied together. In case you run into any issues, head over to our [issue tracker](https://github.com/npruehs/ByChance/issues) and we'll investigate immediately. If you have any questions, don’t hesitate to ask and drop by at our forums or [write us an e-mail](http://www.levelsbychance.com/impressum).