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
