View source for Dice/PbP/RollPost

{{APIdoc|RollPost Class}}
Contains information about all of the rolls on a post, including basic anti-cheat detection.

{{ns|PbP}}

== Inheritance Hierarchy ==
System.Object
:Dice.PbP.RollPost

== Syntax ==
<syntaxhighlight lang="C#">
[Serializable]
public class RollPost : ISerializable, IDeserializationCallback
</syntaxhighlight>

== Constructors ==
{| class="wikitable"
! style="width: 5em" |
! Name !! Description
|-
| {{public}} {{method}} || [[/RollPost ()|RollPost()]] || Constructs a new, empty RollPost.
|-
| {{protected}} {{method}} || [[/RollPost (SerializationInfo, StreamingContext)|RollPost(SerializationInfo, StreamingContext)]] || Constructs a new RollPost using serialized data.
|}

== Methods ==
{| class="wikitable"
! style="width: 5em" |
! Name !! Description
|-
| {{public}} {{method}} || [[/AddRoll (String)|AddRoll(String)]] || Adds a new roll to the post using the DefaultConfig if the roll needs to be evaluated.
|-
| {{public}} {{method}} || [[/AddRoll (String, RollerConfig)|AddRoll(String, RollerConfig)]] || Adds a new roll to the post using the given config if the roll needs to be evaluated.
|-
| {{public}} {{static}} {{method}} || [[/Deserialize|Deserialize(Stream)]] || Deserializes a serialized RollPost.
|-
| {{public}} {{method}} || [[/GetObjectData|GetObjectData(SerializationInfo, StreamingContext)]] || Serializes a RollPost. This method should not be directly called.
|-
| {{public}} {{method}} || [[/HasDivergedFrom|HasDivergedFrom(RollPost)]] || Test if two RollPosts have diverged.
|-
| {{public}} {{method}} || [[/OnDeserialization|OnDeserialization(Object)]] || Completes deserialization of the RollPost once the entire object graph has been deserialized. This method should not be directly called.
|-
| {{private}} {{method}} || [[/PostMacros|PostMacros(MacroContext)]] || Executes PbP-specific macros, which are documented on in the [[Dice Reference#Play-by-Post Macros|dice reference]].
|-
| {{private}} {{method}} || [[/RollMacro|RollMacro(MacroContext, String[])]] || Contains the logic for the {{c|[roll]}} macro.
|-
| {{public}} {{method}} || [[/Serialize|Serialize(Stream)]] || Serializes a RollPost, for saving to the database.
|-
| {{public}} {{method}} || [[/Validate|Validate()]] || Checks if Current has diverged from Pristine.
|}

== Properties ==
{| class="wikitable"
! style="width: 5em" |
! Name !! Description
|-
| {{public}} {{property}} || [[/Current|Current]] || Gets the current version of the post (the one being checked).
|-
| {{protected}} {{property}} || [[/CurrentList|CurrentList]] || Gets the mutable version of Current.
|-
| {{internal}} {{property}} || [[/Diverged|Diverged]] || Gets how diverged Current is from Pristine.
|-
| {{public}} {{property}} || [[/Pristine|Pristine]] || Gets the "pristine" version of the post.
|-
| {{protected}} {{property}} || [[/PristineList|PristineList]] || Gets the mutable version of Pristine.
|-
| {{public}} {{property}} || [[/Stored|Stored]] || Gets the most recent saved version of the post.
|-
| {{protected}} {{property}} || [[/StoredList|StoredList]] || Gets the mutable version of Stored.
|}

== Fields ==
{| class="wikitable"
! style="width: 5em" |
! Name !! Description
|-
| {{private}} {{field}} || [[/_current|_current]] || The current version of the post.
|-
| {{private}} {{field}} || [[/_diverged|_diverged]] || How many levels has Current diverged from Pristine at the moment.
|-
| {{private}} {{field}} || [[/_pristine|_pristine]] || The pristine version of the post.
|-
| {{private}} {{field}} || [[/_stored|_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|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 [[/Deserialize|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 [[Dice/RollResult|RollResults]].

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

<syntaxhighlight lang="C#">
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());
        }
    }
}
</syntaxhighlight>