Capability exercise cost

[kostmo]

Closes #1684
Closes #1262

Demo

A simple "puzzle" that makes use of consumables:

scripts/play.sh -i data/scenarios/Testing/1777-capability-cost.yaml --autoplay

Demo of enabled commands and costs display in left pane:

scripts/play.sh -i data/scenarios/Testing/1262-display-device-commands.yaml

In this PR

• Supports specifying capabilities both as plain lists and as maps from capabilities to ingredients in YAML
• JSON Schema support for both capability specification styles
• New integration test
• Removed redundant tshow implementation from Swarm.Doc.Util

Entity lookup approaches

The cost of exercising a capability in terms of "ingredients" is specified by the _entityCapabilities field within an Entity definition. Each ingredient itself is an entity, specified by name.
For many purposes, having ingredients just of type EntityName is sufficient. But for Swarm.Game.Recipe.findLacking in particular, the ingredients list must be actual Entity objects, not just names of entities. So at some point the names need to be looked up in the global entity map to be promoted to Entity objects.

The full list of entities is not available at Entity parse time to look up an ingredient entity by name, so we cannot store ingredients lists of type (Count, Entity) within a parent Entity object.

Approaches considered were:

• Store a copy of the entityMap in RobotR, for use by the equippedDevices lens
• Introduce a type parameter to Entity representing a "parse phase"
• Allow a redundant "entity lookup" (and validation) at command execution time

Store entityMap in RobotR

One approach explored was to add a field to RobotR:

  , _globalEntityMap :: EntityMap

This allowed the equippedDevices lens implementation to promote the EntityNames to Entitys when setting the value of the _robotCapabilities field. However, it was rather invasive as it entailed threading the EntityMap through many new code paths.

Entity type parameter

Currently, Entity has a field:

_entityCapabilities :: SingleEntityCapabilities EntityName

This would entail a huge refactoring, with:

data Entity e = Entity
  ...
  , _entityCapabilities :: SingleEntityCapabilities e

At initial parse time we would obtain a list of Entity EntityName, but somewhere later during Scenario parse time, we can do another pass to obtain Entity Entity objects.

This would at least have the advantage of doing the entity lookup/validation on ingredient lists in exactly one place, at parse time.

Defer EntityName -> Entity promotion to command execution time

This is what is implemented in this PR. The global set of capability costs is validated at scenario parse time. But it is also redundantly validated in the payExerciseCost function, which is not ideal.

[byorgey]

Suggested change

	type SingleEntityCapabilities e = Capabilities (ExerciseCost e)
	-- | Records an 'ExerciseCost', i.e. list of consumed ingredients, per capability that can be exercised. This represents information about a single entity/device, which can provide multiple capabilities (with a different exercise cost for each).
	type SingleEntityCapabilities e = Capabilities (ExerciseCost e)

[byorgey]

After understanding the relationship between SingleEntityCapabilities and MultiEntityCapabilities, I was kind of expecting to see a function with a type like

Map e (SingleEntityCapabilities en) -> MultiEntityCapabilities e en

(that type might not work as written but hopefully you get the idea). Is there a function like this somewhere in a different module? Can it go in this module instead?

[kostmo]

All review comments now addressed, @byorgey.

[byorgey]

👍