o, have you seen this? -Aris
On Fri, Sep 29, 2017 at 1:00 AM, Aris Merchant <[email protected]> wrote: > On Thu, Sep 28, 2017 at 12:28 AM, Owen Jacobson <[email protected]> wrote: >>> This is the first stage of an attempt to create an annotation system >>> designed to formalize game state changes by attaching formal descriptions >>> of those changes to documents, represented by email messages. At this time, >>> I plan only to archive messages, but there will be a read element allowing >>> anonymous users to read and enumerate messages from the archive in the near >>> future. >> >> The broader scheme here is this: >> >> 1. A client app forwards public messages to the archive. They sit in an >> “unannotated messages” queue until someone - me, probably - picks them up >> and annotates them. >> >> 2. A user annotates each message with a short formal description of the >> game-state changes imposed by a message. These annotations are mutable, so >> mistaken annotations are not a permanent problem, and are versioned so that >> vandalism can be undone. I haven’t worked out the exact schema for these >> annotations, yet, but the concept I’m working with is loosely based on the >> RFC 6902 JSON Patch format, adapted for Agora’s specific needs. For example, >> an annotation transferring shinies might read, in YAML form for readability: >> >>> - op: event >>> office: Secretary >>> summary: o paid Ørjan 1 sh. >>> >>> - op: transfer >>> from: /Shinies/Player/o >>> to: /Shinies/Player/Ørjan >>> delta: 1 >> >> Obviously, this is an awkward format, but it has some nice properties that I >> think make it worth building on. I’m still tweaking the actual format for >> annotaitons, and it’s likely I’ll add a UI or some variety of terse syntax >> so that it’s possible to write this kind of simple action in fewer than >> eight lines. >> >> 3. The archive exposes an API that can sum up the annotations, starting from >> the beginning of time, all the way up to a specific point in time, and then >> return the computed state of the game plus a list of events by office. My >> report scripts will become “query this API in a specific way, and feed the >> resulting data to a template to render it for email.” >> >> The idea is that instead of trying to reduce Agora to a set of formal >> actions, I instead want to keep the prose forms as the primary documents and >> allow formal note-taking alongside them. Many of Agora’s state changes are >> formalizable, and from there, those parts of Agora’s state are computable, >> so this could take a bunch of load off for computing those parts of the game. >> >> I’ve had some success with a reduced version of this approach for the office >> of Surveyor. All Surveyor’s reports have been generated by a >> built-to-purpose Python script that applies the same principles to a set of >> local YAML files instead of a web API. >> >> -o > > I love this idea. It seems very practical without sacrificing > usability for the end users (i.e. the players). I have a few > suggestions: > > 1. Who annotates. I think giving everyone access to the annotation > interface would probably make sense. You can't personally annotate > every message affecting the entire gamestate, and I'd love to help set > the formats I'm consuming for Promotor. nichdel came up with a > proposal format suggestion, and now that this has come along I'm > modifying it to have more information for the Promotor side of the > Promotor-Assessor pipeline. I'm sure other officers have input on how > formalization for their parts of the gamestate should take place, and > they have a unique understanding of what information is needed to do > their jobs. > > 2. Annotation style. As you've mentioned, your format is a bit forced. > You're doing a great job with what you have to work with, but I think > the basic problem may be that you're trying to use markup to represent > transactions. It works wonderfully for representing the data (and > should probably be a base format for that), but poorly for > representing things like conditional actions. You can add and add to > the format, but you'll just be making it more complicated to use. I > suggest you consider using programs (possibly with methods you > provide) as annotations. It feels kind of intuitively weird to > represent an annotation as a program, and they don't have the nice > formal properties the data itself does (except maybe if you used > Haskell or something), but I think it might be a lot more practical > for actual use. Programs allow for loops, unrestricted conditionals, > and the like, meaning that you don't have to work something out by > hand or create a new transaction type just for one complicated > transaction. They would work well for this because they take data and > compute changes, which is exactly what our action system does. There > is thus a neat one-to-one correspondence between an action and a > program. > > o, honestly, this is an amazing idea. This is such a brilliant > solution to the entire problem that I'm kind of kicking myself for not > coming up with it (not that I would have been able to implement it if > I had). > > -Aris
