Dice/PbP/RollPost

Contains information about all of the rolls on a post, including basic anti-cheat detection.

• Namespace: Dice.PbP
• Assembly: DiceRoller (in DiceRoller.dll)

Inheritance Hierarchy

System.Object

Dice.PbP.RollPost

Syntax

[Serializable]
public class RollPost : ISerializable, IDeserializationCallback

Constructors

	Name	Description
	RollPost()	Constructs a new, empty RollPost.
	RollPost(SerializationInfo, StreamingContext)	Constructs a new RollPost using serialized data.

Methods

	Name	Description
	AddRoll(String)	Adds a new roll to the post using the DefaultConfig if the roll needs to be evaluated.
	AddRoll(String, RollerConfig)	Adds a new roll to the post using the given config if the roll needs to be evaluated.
S	Deserialize(Stream)	Deserializes a serialized RollPost.
	GetObjectData(SerializationInfo, StreamingContext)	Serializes a RollPost. This method should not be directly called.
	HasDivergedFrom(RollPost)	Test if two RollPosts have diverged.
	OnDeserialization(Object)	Completes deserialization of the RollPost once the entire object graph has been deserialized. This method should not be directly called.
	PostMacros(MacroContext)	Executes PbP-specific macros, which are documented on in the dice reference.
	RollMacro(MacroContext, String[])	Contains the logic for the [roll] macro.
	Serialize(Stream)	Serializes a RollPost, for saving to the database.
	Validate()	Checks if Current has diverged from Pristine.

Properties

	Name	Description
	Current	Gets the current version of the post (the one being checked).
	CurrentList	Gets the mutable version of Current.
	Diverged	Gets how diverged Current is from Pristine.
	Pristine	Gets the "pristine" version of the post.
	PristineList	Gets the mutable version of Pristine.
	Stored	Gets the most recent saved version of the post.
	StoredList	Gets the mutable version of Stored.

Fields

	Name	Description
	_current	The current version of the post.
	_diverged	How many levels has Current diverged from Pristine at the moment.
	_pristine	The pristine version of the post.
	_stored	The stored version of the post.

Remarks

When a new post is made, a new RollPost instance should be constructed and stored along with that post in the database (using the Serialize() method, it is recommended that a DeflateStream is passed or some other compression stream). The AddPost() method is used to add rolls to the post, and Validate() is used to determine if the post has been modified in a way that indicates cheating. Even if you do not care about the cheating detection, Validate() must be called before serializing a RollPost. If you do not do this, the Pristine version of the roll will not be updated, which can cause issues down the line for future edits causing expressions to be rerolled instead of taking on their prior values.

When processing an existing post, deserialize the stored RollPost via RollPost.Deserialize(), then call AddRoll() again for all rolls in the post. RollPost will re-use previously rolled values for those rolls if possible, otherwise it will reroll them. After all rolls have been added via AddRoll(), Validate() should be called to determine whether or not cheating happened and to update some internal state, and then you can iterate over Current to retrieve all of the individual RollResults.

Examples

The following example simulates creating and saving a new post, and then later loading it to inspect the rolled values.

using System;
using System.IO;
using System.IO.Compression;

using Dice;
using Dice.PbP;

class Sample
{
    public static void Main()
    {
        MemoryStream stream = new MemoryStream();

        // pretend our post had 2 rolls: 1d20+4 and 2d6+3/4d6+6
        RollPost post = new RollPost();
        post.AddRoll("1d20+4");
        post.AddRoll("if([roll:1:critical], >0, 4d6+6, 2d6+3)");
        post.Validate(); // must be called every time, including on initial post

        // passing true as 3rd param leaves stream open, otherwise DeflateStream closes it
        // when disposing. Data is not written to stream until deflate is disposed.
        using (var deflate = new DeflateStream(stream, CompressionLevel.Optimal, true))
        {
            post.Serialize(deflate);
        }
        // save contents of stream along with the post to the database...
        // for this example we just rewind the stream
        stream.Seek(0, SeekOrigin.Begin);

        // later: retrieve serialized post from database, store it in stream...
        using (var deflate = new DeflateStream(stream, CompressionMode.Decompress))
        {
            post = RollPost.Deserialize(deflate);
        }
        // need to re-add the rolls on the current version of the post,
        // even if they didn't change
        post.AddRoll("1d20+4");
        post.AddRoll("if([roll:1:critical], >0, 4d6+6, 2d6+3)");
        if (!post.Validate())
        {
            // if post.Validate() returns false, this indicates that the rolls were
            // tampered with. Highlight this somehow on the post (perhaps with a scary
            // warning sign in the post background).
        }

        // iterate over the results so we can display them
        foreach (RollResult result in post.Current)
        {
            Console.WriteLine(result.ToString());
        }
    }
}