Notion of computedProperties

[jkomoros]

Things that can be fully derived from the rest of state, but are useful to have, or expensive to calculate.

In the future it will be nice to be able to create little bundles of script that can be runclientside to create these, too.

gameView.expandGameState should be where we calculate and plug those in.

Part of this was originally captured in #79

[jkomoros]

dynamic groups for sanitization feel similar. #160

[jkomoros]

Notion of computedProperties on GameManager.

func(state State) interface{}, stored in a map. After each state update, run them and store the results in a map[string]interface{}.

Ideally there'd be some type safety, and some way to cache the results by defining the properties they depend on or something.

[jkomoros]

In a perfect world they'd e wired up so that the State object would be able to return them, too--does that require states to have a link back to manager?

Then anyone with a State object could treat computedProperties mostly like just normal properties.

[jkomoros]

You could have State. have a computedProperties taht returns a PropertyReader object that has an underlying concrete type like States do.

[jkomoros]

States grow a Computed() *ComputedProperties method.

Under the covers, their impl does this:

if (s.computed == nil) {
  s.computed = boardgame.NewComputedProperties(state, config)
}
return s.computed

Where config is a collection of maps and stuff that was created once in their state.go and then handed out there.

const LegaPropertyType TypeInt TypeBool TypeGrowableStack TypeSizedStack ... )

ComputedProperties has: Props() map[string]LegalPropertyType, as well as IntProp(name) int, BoolProp(name) bool, etc.

... is that the signature that PropertyReader should have??

TODO: how do we handle properties for a specific user, like HandValue?

[jkomoros]

• [ ] Make blackjack.HandValue be a computed property

[jkomoros]

If that is the new signature of PropertyReader, (a Reader()) then we can have a Computed() that also returns a PropertyReader. Easy peasy!

... Except how to handle the notion of a property for a specific User.

Nah, that's fine, if ComputedProperties embeds PropertyReader as well as Player(index int) PropertyReader

[jkomoros]

There are some use cases where the input to the computedProperty has to look at all state (e.g. numGhosts). There are some use cases where it should be tied to a specific PlayerState.

[jkomoros]

There are two types of computed properties: generic ones and player-specific-ones.

type ComputedProperties interface {
  PropertyReader
  Player(index int) PropertyReader
}

This will be much nicer to use once #164 is fixed and PropertyReader has convenient typed getters.

[jkomoros]

In practice most states will create a DefaultComputedProperties like so:

//In boardgame

type PropertyComputer func(state State) interface{}

type DefaultComputedProperties struct {
  config *ComputedPropertiesConfig
  memoizedValues <whatevertype>
}

var myConfig *boardgame.ComputedPropertiesConfig

func init() {

  //The config is an expensive, big object--so we should compute it once when we init and then use the same one everywhere.
  //TODO config should actually be split up by types, ala propertyReader.
  myConfig = &boardgame.ComputedPropertiesConfig{
    Game: map[string]boardgame.PropertyComputer{
      "NumGhosts" : func(state) interface{} {
           s := state.(*myState)
           return s.NumGhosts()
      }
    },
    Player: map[string]boardgame.PropertyComputer {
      "HandValue" : func(state, index) interface{} {
        s := state.(*myState)
        p := s.Players[index]
        return p.HandValue()
      }
    }
  }
}

func (s *State) Computed() boardgame.ComputedProperties {
  if s.computed == nil {
    s.computed = boardgame.NewDefaultComputedProperties(s, myConfig)
  }
  return s.computed
}

ComputedPropertiesConfig is kind of ugly to expose from boardgame, which implies that it's actually a sub-package that does it, similar to #132

[jkomoros]

As noted in the example above, the majority of funcs will be small shims that just call the equivalent method on the specific concrete state struct underneath.

The map[string]boardgame.PlayerPropertyComputer and all of that is so messy--such long variables! That again is an argument for it being in a sub-package, ala #132.

[jkomoros]

ComputedProperties should be exported to the client-side state object somehow

[jkomoros]

ComputedProperties shoudl return an error if the state object htey are given is sanitized in a way that makes it impossible to calculate the real value. Basically, they might be passed a sanitized or unsanitized state and they shoudl be resilient to that.

[jkomoros]

The hard part is that ComputedProperties need to be able to handle sanitized values, which might invalidate some of them.

[jkomoros]

Also, properites could rely on other properties...

[jkomoros]

Also, the interface of PropertyReader/Player(int)PropertyReader doesn't work, because some computed properties need to get the entire state object.

Ideally your config would include which properties you depended on (other computed properties, game properties, player state properties (if you asked for one you'd get them all)) and you'd be handed a PropertyReader with that information and just that information. That would help ensure that you actually defined your dependencies. And then we could calculate the dependency chain for computed properties that rely on other computed properties.

[jkomoros]

Computed properties likely require more proprerty types. Like blackjack.EffectiveHand is a playingcards.card. So I guess just have an interface for the unsupported types? (gross)

[jkomoros]

Also, obviously, computed state's property reader should lazily calculate the properties

[jkomoros]

type GroupType int

const (
  GroupGame GroupType = iota
  GroupPlayer
  GroupComputedProperty
)

type StatePropertyRef struct {
  Group GroupType //If GroupType is GroupPlayer, then we'll make sure that each player is referenced
  PropName string
}

type PlayerStatePropertyRef string

func (s *StatePropertyRef) Value(state *State) interface{} {
  // Fetch the given property from the state and return it
}

[jkomoros]

type ComputedPropertyDefinition struct {
  Arguments []StatePropertyRef
  //F will be called with the Value() of each StatePropertyRef in arg called, in order.
  F func(...args interface{}) (interface{}, error)
}

[jkomoros]

type ComputedPropertyReader {
  PropertyReader
  Player(index int) PropertyReader
}

func (s *State) Computed() ComputedPropertyReader {
  //Either memoized to only return the ones that are asked for, or precomputed (if we store all of them every time)
}

[jkomoros]

It seems really finicky to have everything be interfaces. I like the idea that you describe what your inputs are from state, and we return a State-like thing that has PropertyReaders that will error if you touch one you didn't tell us you needed.

type ComputedProperties interface {
  PropertyReader
  Player(int) PropertyReader
}

func (s *State) Computed() ComputedProperties {
  //Lazily creates a new computedProperties by passing the config from delegate.ComputedPropertiesConfig
}

type ComputedPropertiesConfig struct {
  Definitions map[string]ComputedPropertyDefinition
  PlayerDefinitions map[string]ComputedPlayerPropertyDefinition
}

type GameDelegate interface {
  //...

  //Returns the config to use for computing properties
  ComputedPropertiesConfig() ComputedPropertiesConfig

  //...
}

type ShadowPlayerState struct {
  PropertyReader
  Computed PropertyReader
}

//These are passed to the Func of ComputedProperty. Reading a property that wasn't configured as a dependency will return a zero value and error.
type ShadowState struct {
  Game PropertyReader
  Players []ShadowPlayerState
  Computed PropertyReader
}

type ComputedPropertyDefinition struct {
  Dependencies []StatePropertyRef
  //F will be called with a shadow state where you are only allowed to read out the properties you listed as dependencies. 
  F func(state *ShadowState) (interface{}, error)
}

type PlayerStatePropertyRef struct {
  Group GroupType //only Player, Computed allowed
  PropName string
}

type ComputedPlayerPropertyDefinition struct {
  Dependencies []PlayerStatePropertyRef
  F func(playerState *ShadowPlayerState) (interface{}, error)
}

[jkomoros]

Hmmm, PlayerComputedProperty feels very different from GlobalComputedProperty. How do we store the computed properties when we serialize them? I guess in the Computed JSON blob that's exported we also export an array of PlayerComputedProperties, one for each player.

[jkomoros]

• [x] Stub out all of the properties and types
• [x] ComputedPropertyDefinition.Compute()
• [x] Test computedPropertyDefintion.Compute()
• [x] computedPlayerImpl fetches from storage, or computes and stores.
• [x] Test Computed property round trips
• [x] Output computed properties in JSON
• [x] Add ComputedPlayer properties
• [x] computedPlayerPropertiesImpl should not anonymously embed bag; implement all of the getters to compute the value if necessary (pop out impls from non-player?)
• [x] MarshalJSON outputs ComputedPlayer properties
• [x] Test computedPlayer properties end to end
• [x] PlayerState definitions should barf if the GroupType in StateRef is not player
• [x] Verify that when a state is created sanitized that the Result should follow sanitization rules
• [x] Allow depending on other computed properties
• [x] Test
• [x] Should the Computed() be on PlayerState? (But then everyone would have to compute their own
• [x] Injest computed properties from JSON (new issue?)
• [x] Only recalc properties when their dependencies change (new issue?)
• [x] Make HandValue in BlackJack a computed Property ... did most of the work, but it was a PAIN to use a ComputedProperty everywhere...
• [x] Figure out a more convenient, type-check-y way to grab computed props for practical use in a state. Like maybe a pattern where the same method is written so that you write a small shim around it to pass in shadow values or real values, and your playerStates can have methods? Or a method in boardgame where you pass in a struct and it fetches all of the named properties into it, erroring if any are unknown or fail. (That's only useful if you're fetching multiple computed properties at once)
• [x] Consider whether we should have Computed marshal JSON to Props and Players (or something), so that top level computed props aren't mixed in with the Players sub-dictionary. Will be hard to parse later otherwise...
• [x] Rationalize names of all exposed new types
• [x] Document all of the new types in computed.go
• [x] Update all of doc.go and godoc with info on computed properties (make sure your Compute function is resilient to sanitized values; make sure they're deterministic)