% CSci 658: Software Language Engineering \
  Adventure Game SCV Analysis
% **H. Conrad Cunningham**
% **25 April 2018**

## Scope

We limit the scope of our adventure game DSL and semantic model as follows:

-   choose-your-own adventure game
-   only one level of play
-   text-based interface (no graphics)
-   process of configuring the world
-   probably more restrictions

Issue:  So far, we have not handled actions and their consequences
sufficiently precisely to specify the commonalities.

My example: Wizard's Adventure Game from *Land of Lisp* that I
reimplemented in Elixir.


## Terminology from OO Analysis

This is modified some from in-class analysis.

-    location
-    connection
-    item (movable)
-    location description 
-    connection description
-    item description
-    mapping of items to locations 
-    player(s)
-    player's inventory 
-    player's location 
-    state variables?
-    actions


## Toward Commonalities

1.  A world has a finite but unbounded collection of distinct locations (0 or
    more).
	
	Note: I added "distinct" and "unbounded" parts after class.

    Issues: 
	-   finite or infinite cardinality?
	-   bounded above or unbounded?
	-   bounded below? 
	-   0?


#.  FOR DISCUSSION: The collection of locations in a world cannot
    change after configuration.
	
	Issues:
	-   static? dynamic? (i.e. collection immutable or mutable?)
	-   if dynamic, how do we define allowed changes 


#.  Each location has a unique name separate from its description.

    Issues:
	-   no name? one name? more than one name?
	-   name separate? or as part of description?
	-   name unique within world?
	-   do we need a separate id for locations (e.g. small integer)?


#.  FOR DISCUSSION: A location's name cannot change after
    configuration.
	
	Issues:
	-   static? dynamic?  (i.e. immutable or mutable?) 
	-   if dynamic, how do we define allowed changes


#.  Each location has a description.

    Issues: 
	-   no description? 
    -   more than one description? 


#.  FOR DISCUSSION: A location's description cannot change after
    configuration.
	
	Issues:
	-   static or dynamic? (i.e. immutable or mutable?)
	-   if dynamic, how do we define allowed changes 


#.  A world has a possible directed connection between any pair of
    locations in the world. The actual connections present are a
    subset of this set.
	
	Issues:
	-   allow possible connections to be absent?
    -   only between pairs of locations? or connect more than 2
        locations? connect a location with itself?
    -   allow more than 1 connection between pair of locations? 
	-   directed or undirected connection?
    -   finite or infinite? 0 or more? (determined by other choices)
	
	Note: We are thinking about the world being modeled by some kind
    of graph structure. These issues and those for locations explore
    the nature of that graph.


#.  FOR DISCUSSION: The collection of connections in a world cannot
    change after configuration.
	
	Issues:
	-   static? dynamic? (i.e. collection immutable or mutable?)
	-   if dynamic, how do we define allowed changes 


#.  A connection does not have a separate name.

    Issues: 
	-    no name? one name? more than on name? 
	-    name unique within world? 

    Assumption: Given the above assumes a simple digraph model, a
    connection can be identified by the pair of nodes it connects and
    its direction. Its description can also provide additional
    differentiation.


#.  Each connection has a description.

    Issues: 
	-   no description? 
    -   more than one description? 


#.  FOR DISCUSSION: A connection's description cannot change after
    configuration.
	
	Issues:
	-   static? dynamic?
	-   if dynamic, how do we define allowed changes 


#.  FOR DISCUSSION: A world has a finite but unbounded collection 
    of distinct items.

    Issues:
	-   finite or infinite?
	-   bounded above or unbounded?
	-   bounded below?
	-   0?


#.  FOR DISCUSSON: The collection of items cannot change after
    configuration.
	
	Note:  I am unsure about the choice here.

    Issues:
	-   static or dynamic?
	-   if dynamic, how do we define allowed changes 


#.  FOR DISCUSSION: Each item instance is atomic.

	Note:  I am unsure about the choice here, but probably okay.
	
	Issues:
	-  is an item indivisible/atomic? 
	-  can it be split or combined?


#.  FOR DISCUSSION: Each item has a unique name.  The name cannot
    change after configuration.  (Break into 2 statements?)
	
	Note:  I am unsure about the choice here. Perhaps we just want a
    type name like "bucket" rather than "bucket1" and "bucket2". Or
    maybe we need both kinds of names.
	
	Issues:
	-  does an item have an individual name? a name of the kind
       of object it is? both? or no name?


#.  FOR DISCUSSION: Each item has a description.  The description
    cannot change after configuration.   (Break into 2 statements?)
	
	Note:  I am unsure about the choice here. We may not need this for
    the game.
	
	Issues:
	-   does it have a description? how does that differ from name?
	-   can description be null?


#.  FOR DISCUSSION: Each item has a position at any point in
    time.  The position may change during the game.  (Break into 2
    statements?)
	
	Issues:	
	-   can it be split across multiple positions? or just one? or
        nowhere inside game?
	-   can a position change spontaneously? or only under player
        control?
	-   if it can change, what are the allowed changes


#.  FOR DISCUSSION: A position is any location (name) or a player inventory.

    Issues:
	-   are there other places we need to consider?


#.  FOR DISCUSSION: The world has a finite but unbounded collection of
    distinct state variables, each of which has a unique name, a set
    of possibly participating items, and a set of possible states.
	
    The parts about possible participants and possible states may not
    be quite what is needed.
	
	In the Wizard's game, these are states like the the chain and
    bucket being welded together or the bucket being filled (with
    water).
	
	Do we have multiple state variables with the same name but
    different participants?
	

#.  FOR DISCUSSION: There is one human player and no similar automated
    players.

    Issues:
	-   one player? multiple human players? no human players?
	-   automated players?
	-   Are there non-player characters or agents that can cause some
        changes?


#.  FOR DISCUSSION: Each player has a unique current location in the world.

    Issues:
	-   at a location? 
	-   at a connection?
	-   in more than one place at once? in no place inside world?
	

#.  FOR DISCUSSION: Each player has an inventory of items being held.

    Issues:
	-   finite or infinite?
	-   bounded below or above?
	-   can it change spontaneously?


#.  FOR DISCUSSION: The world has a finite but unbounded collection of
    actions. Each action has a unique name, a subject, an object,
    a transformation of the world, and a result.
	
	This is too vague and imprecise. Not quite right!
	
	What about builtins like look, walk, inventory?

    Are these in scope of configuration?


## Toward Variabilities

1.  What locations in collection. Each location's name and description.

#.  What connections in collection. Each connection's source and target
    locations. Each's description.
	
#.  What items in collection. Each item's name, description, and
    current position.
	
#.  What items are in the player's inventory.

#.  What state variable in collection. Each's name, list of possible
    participants, and possible states. Each also have a current list
    of participants and current state.

#.  What are the actions?



## Toward a Possible Semantic Model (Python)

Underlying model is a digraph with "labels" (data) on each
node and each edge. Here I use something like a node adjacency list structure.

-   Collection of locations is a mapping from a name to its
    description. (Names are unique within the collection.)
	
-   Collection of connections is a mapping from a source location name
    to a pair consisting of the destination location and the
    description of the connection. (Names are unique within the
    collection.) (This could be two mappings instead of a mapping to a
    tuple.)

-   Collection of items is a mapping from an item name to its
    description.  (Names are unique within the collection.)
	
-   Current item positions are given by a mapping from a name to a
    location name, where there is a special reserved name
    (e.g. "inventory" but cannot be a valid location name) to denote a
    player's inventory.
	
	I kept this separate from the previous mapping because the
    positions change but the descriptions do not.
	
	If more than one player, then inventory idea is probably player
    name.
	
-   Collection of state variables is a mapping between the state
    variable name and



##  Toward a Possible External DSL

Here is a rough grammar for a possible external, text-based DSL:

-   WORLD -> { LOCATION } { CONNECTION } { ITEM } { STATEVAR }

-   LOCATION  -> location LNAME LDESCRIPTION

-   CONNECTION -> connection LNAME LNAME CDESCRIPTION

-   ITEM -> item INAME IDESCRIPTION IPOSITION

-   IPOSITION -> in LNAME  | inventory

-   STATEVAR -> variable VNAME PARTICIPANTS STATES

-   PARTICIPANTS -> INAME  | ( INAME { , INAME } )

-   STATES -> ( SNAME { , SNAME } )

LDESCRIPTUIN and CDESCRIPTION are probably quoted strings.

LNAME, INAME, VNAME, and SNAME are probably identifier-style strings
that are not keywords. They can probably have separate namespaces for
each kind.

The keywords are location, connection, item, in, and inventory. Open
and closed parentheses and commas are also terminal symbols.

We are not handling ACTIONS here.  State variables are probably not
correct.


## Toward a Possible Internal DSL (Python)

For discussion.