The implementation and design of custom scripts in chiventure will depend on the implementations of WDL (how custom scripts are specified), Game State (how information about custom scripts are stored in the game struct), and Action Management (how custom scripts are run). Ensuring other teams are aware of these dependencies of custom scripts, over this past week, I have been communicating with the relevant teams, understanding what they have done and planned, and discussing our preliminary design for custom scripts and the potential dependencies that come along with it.

The following note documents dependencies and requirements from the custom scripts team that other teams can refer to.

• Point of contact: Isaac Fink
• Meeting time: May 8th
• Action management does not plan to undergo a major restructuring like WDL++ is
• One of action management’s main responsibility is to execute an action from an action struct that they create themselves and an item struct:
  • This action struct is needed for two reasons
  1. Items can have multiple actions ⇒ Need to specify which action within the item to execute
  2. Actions have different types ⇒ Need to specify which do function to run
  • Since these two situations also apply to actions that are executed with custom scripts, it makes sense for action management to also create an action_type_t struct for custom script actions.
• Therefore, a new kind of action, on top of the current three (item, path, and item-item) should be created (e.g. lua --- see dependencies summary below)
• Also, a new do function would, thus, have to be created (e.g. do_lua_action() --- see dependencies summary below for more thorough requirement details)
  • We will handle the implementation ourselves, meaning we will not only execute the Lua script (which involves passing data on and off the stack), but also the overhead involved (opening the Lua state, libraries, etc.)
  • Since the Lua script will likely require information about the context of the game, most likely need to pass this function a game_t argument on top of the action and the item
  • This will also require a separate action function in CLI’s operation.c/.h file that calls this do_lua_action() function (e.g. kindlua_action_operation() --- see dependencies summary below)

• New action kind for Lua actions

  enum action_kind {
      ITEM = 1, // ACTION <item> i.e. Action Type 1
      PATH = 2, // ACTION <path i.e. Action Type 2
      ITEM_ITEM = 3 // ACTION <item> <item> i.e. Action Type 3
      LUA = 4 // Action Type 4 (Lua)
  };
  

• Ability to create action_type_t struct for custom script actions
  • E.g. action_type_t lua_action = action_type_new(char * c_name, enum action_kind LUA)
    • This should be possible already based on the current implementation of action_type_new(...) and action_type_init(...)
• A do function for custom script actions like do_item_action(...), do_path_action(...), do_item_item_action(...)
  • E.g. do_lua_action(action_type_t *a, item_t *i, game_t *g, char **ret_string)
    • game_t argument needed as the Lua script would likely have to do conditional checks on the current game state (such as accessing information about the inventory, rooms, etc.)
      • This is possible as actionmanagement.h includes game-state/game.h
• A parent function in cli/src/operations.c that calls do_lua_action(...) like kind1_action_operation(...), kind2_action_operation(...), kind3_action_operation(...)
  • E.g. kind4_action_operation(char *tokens[TOKEN_LIST_SIZE], chiventure_ctx_t *ctx) that extracts the game_t from ctx, finds the desired action and item from tokens, and passes them into do_lua_action(...)

• Point of contact: Elaine Wan and Nam Anh Dinh
• Meeting time: May 9th and May 11th
• WDL plans to retain the hierarchical nature of the YAML version but intends to split each layer into its own individual JSON file. WDL's design documentation can be found here
  • Items will be specified in items.json and each item will contain a list of actions, which are specified in actions.json.
• Coordinating with Team Custom Actions, WDL++ will change the specification of actions slightly
  • Actions will be defined as "action sequences" that are composed of a set of atomic actions such as if, set, move, etc.
    • These atomic actions can be found in Custom Actions' design documentation here
  • Each of these atomic actions will reside and be specified in their individual block
    • E.g. (subject to change depending on WDL++'s final design)

    "action" : [
       {
          "id": "my_action_id",
          "context": "item",
          "item": "obj_CHAIR",
          "sequence": [
              {"block": "if", "params": "inventory has item_SPINACH"},
              {"block": "set", "params": "arg1 flipped"},
              {"block": "say", "params": "'You pushed the chair. It flipped!'"},
              {"block": "else", "params": ""},
              {"block": "say", "params": "'Couldn't push the chair. Spinach needed.''"},
              {"block": "endif", "params": ""},
              {"block": "say", "params": "'This is printed regardless of push success.'"},
           ]
        }
    ]
    

  • But a sequence can also be made up of just one Lua script, which is what we are concerned with (see dependencies summary below)
• WDL++ will also be responsible for parsing as well. Therefore, information about the custom script must be obtainable from the game_action_t struct of the item_t struct (see dependencies summary below)

• Ability to include a Lua script for an action of an item that the game-author wants to add custom scripts for
  • In actions.json, something like this should be supported:

    "action" : [
       {
          "id": "my_action_id",
          "context": "item",
          "item": "obj_CHAIR",
          "sequence": [
              {"block": "lua", "params": "'path/to/example.lua' arg0 arg1 arg2 arg3"}
           ]
        }
    ]
    

• Additional field in game_action_t struct of the item_t struct specifying the directory of the Lua file
  • E.g. char* lua_directory:

    typedef struct game_action {
        UT_hash_handle hh;
        char* action_name;
        char* lua_directory; // NULL if action doesn't have custom script
        action_condition_list_t *conditions; 
        action_effect_list_t *effects; // this may change with the implementation of custom actions (irrelevant to us)
        char* success_str;
        char* fail_str;
    } game_action_t;
    

• Point of contact: Zachary Wu
• Meeting time: May 7th and May 8th
• Custom Actions is planning to create a dictionary of more complex actions for users to select from. These actions will be created from blocks and are complementary to the current hard-coded actions
  • They will handle the execution of these custom actions
  • They will not use custom scripts (no dependencies on us)
• Separate from Custom Scripts ==> game-authors will have two ways to design custom actions
  • To use the predefined sequences and blocks that custom actions will provide (functionalities include atomic conditionals and effects)
  • To use Lua scripts for more complex actions that custom actions can not support (e.g. custom actions within custom actions)
• Similar to us, they will be working with Action Management and WDL++, requiring a separate action kind and specification for these action blocks in actions.json

• Our dependencies on other teams are similar, and we are both providing game-authors the ability to create custom actions. However, both teams do not foresee dependencies on each other as long as the game_action_t structs are well defined (e.g. an action should not have both a custom action/action sequence definition and a custom script definition)