< Dice‎ | PbP

Difference between revisions of "Dice/PbP/RollPost"

From DiceRoller Documentation
(Created page with "{{APIdoc|RollPost Class}} Contains information about all of the rolls on a post, including basic anti-cheat detection. {{ns|PbP}} == Inheritance Hierarchy == System.Object :...")
 
(+example)
Line 80: Line 80:
  
 
When processing an existing post, deserialize the stored RollPost, 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]].
 
When processing an existing post, deserialize the stored RollPost, 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.Runtime.Serialization.Formatters.Binary;
 +
 +
using Dice;
 +
using Dice.PbP;
 +
 +
class Sample
 +
{
 +
    public static void Main()
 +
    {
 +
        BinaryFormatter formatter = new BinaryFormatter();
 +
        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
 +
 +
        formatter.Serialize(stream, post);
 +
        // 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...
 +
        post = (RollPost)formatter.Deserialize(stream);
 +
        // 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>

Revision as of 23:12, 19 April 2017

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.
GetObjectData(SerializationInfo, StreamingContext) Serializes a RollPost.
OnDeserialization(Object) Completes deserialization of the RollPost once the entire object graph has been deserialized.
PostMacros(MacroContext) Executes PbP-specific macros, which are documented on in the dice reference.
RollMacro(MacroContext, String[]) Contains the logic for the [roll] macro.
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.
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 BinaryFormatter to serialize it). 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, 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.Runtime.Serialization.Formatters.Binary;

using Dice;
using Dice.PbP;

class Sample
{
    public static void Main()
    {
        BinaryFormatter formatter = new BinaryFormatter();
        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

        formatter.Serialize(stream, post);
        // 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...
        post = (RollPost)formatter.Deserialize(stream);
        // 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());
        }
    }
}