< Dice‎ | PbP

Difference between revisions of "Dice/PbP/RollPost"

From DiceRoller Documentation
(+example)
 
(2 intermediate revisions by the same user not shown)
Line 33: Line 33:
 
| {{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}} {{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}} {{method}} || [[/GetObjectData|GetObjectData(SerializationInfo, StreamingContext)]] || Serializes a RollPost.
+
| {{public}} {{static}} {{method}} || [[/Deserialize|Deserialize(Stream)]] || Deserializes a serialized RollPost.
 
|-
 
|-
| {{public}} {{method}} || [[/OnDeserialization|OnDeserialization(Object)]] || Completes deserialization of the RollPost once the entire object graph has been deserialized.
+
| {{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}} || [[/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.
 
| {{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.
 
| {{public}} {{method}} || [[/Validate|Validate()]] || Checks if Current has diverged from Pristine.
Line 52: Line 58:
 
|-
 
|-
 
| {{protected}} {{property}} || [[/CurrentList|CurrentList]] || Gets the mutable version of Current.
 
| {{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.
 
| {{public}} {{property}} || [[/Pristine|Pristine]] || Gets the "pristine" version of the post.
Line 77: Line 85:
  
 
== Remarks ==
 
== 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 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, 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 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 ==
 
== Examples ==
Line 87: Line 95:
 
using System;
 
using System;
 
using System.IO;
 
using System.IO;
using System.Runtime.Serialization.Formatters.Binary;
+
using System.IO.Compression;
  
 
using Dice;
 
using Dice;
Line 96: Line 104:
 
     public static void Main()
 
     public static void Main()
 
     {
 
     {
        BinaryFormatter formatter = new BinaryFormatter();
 
 
         MemoryStream stream = new MemoryStream();
 
         MemoryStream stream = new MemoryStream();
  
Line 105: Line 112:
 
         post.Validate(); // must be called every time, including on initial post
 
         post.Validate(); // must be called every time, including on initial post
  
         formatter.Serialize(stream, 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...
 
         // save contents of stream along with the post to the database...
 
         // for this example we just rewind the stream
 
         // for this example we just rewind the stream
Line 111: Line 123:
  
 
         // later: retrieve serialized post from database, store it in stream...
 
         // later: retrieve serialized post from database, store it in stream...
         post = (RollPost)formatter.Deserialize(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,
 
         // need to re-add the rolls on the current version of the post,
 
         // even if they didn't change
 
         // even if they didn't change

Latest revision as of 00:48, 6 October 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.
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());
        }
    }
}