Custom Actions ~ Current State and Future Plan of Custom Actions

A brief summary of the current state of Custom Actions for the use of integrating it into action_management and chiventure as a whole.

Connected to issue 878

The Current State of Custom Actions

Currently Custom Actions is implemented with a system of structs called blocks, which are one of 4 types. AST_block_t is a wrapper for these 4 types that will be detailed after the individual types.

Note for the implementation of the blocks: All of them currently have init, new, AST_new, and free funtions, which aren't note in implementation. AST_new creates an AST_block_t. Example: AST_action_block_new creates an AST_block_t with block_type ACTION.

1. Action Blocks

Found in action_block.h

typedef struct action_block {
    action_enum_t action_type;
    int num_args;
    attribute_t** args;
} action_block_t;

Action blocks are how custom actions modify attributes. Currently, they only take mathematical action types, a number of arguments to modify, and the list of arguments that they are modifying.

Current Implementation and Planned Implementation

Actions blocks are implemented to work for mathematical operators using the function int exec_action_block(action_block_t *a. Action types outside of mathematically changing attributes are planned, such as executing a lua script or moving something;s room.

2. Branch Blocks

Found in branch_block.h

typedef struct branch_block {
    int num_conditionals;
    conditional_block_t** conditionals;
    conditional_type_t conditional_type;
    int num_controls;
    control_block_t** controls;
} branch_block_t;

Branch blocks are designed for representing conditional functions inside of custom actions. Control blocks represent the kind of conditional function that the branch is representing. It uses a list of conditional_block to determine how it branches and when executed will evaluate the conditionals and execute the proper control_blocks.

Current Implementation and Planned Implementation

Currently, there is no implementation for branch_block. Pull Request 802 contains minor implementation, but the function has been commented out with the note that branch_block is outdated. To make branch blocks functional, the branch_block struct needs to be updated to contain the actions that it is branching into.

typedef struct branch_block {
    int num_conditionals;
    conditional_block_t** conditionals;
    control_type_t control_type;
    int num_actions;
    AST_block_t** actions;
} branch_block_t;

Conditional functionality remains the same, but is instead of the function being determined by the control block, the enum is being directly stored in the branch_block. The actions to be done are now stored in an array of AST_block_t. This is specifically AST_blocks, so that they can be either action blocks or branch blocks.

3. Conditional Blocks

Found in conditional_block.h

typedef struct conditional_block {
    conditional_type_t conditional_type;
    attribute_t* left;
    attribute_t* right;
} conditional_block_t;

A struct that contains pointers to attributes that it compares with a given method of comparison (conditional_type_t).

Current Implementation and Planned Implementation

Pull Request 802 has a function for evaluating a conditional partially written, but it is not complete or merged. There is no implementation currently in dev. There is not much implementation to be added for conditional blocks. Finishing the evaluation function and potentially adding more things to conditional_type.

4. Control Blocks

Found in control_block.h

typedef struct control_block {
    control_type_t control_type;
} control_block_t;

Originally, it was intended to contain a control type and an action. However, changes made to AST_block have made this useless as it only contains a control type.

Current Implementation and Planned Implementation

Currently, there is no implementation for control blocks. In their current state, they are the same as the control_type enum. Once control blocks are removed from branch blocks, control blocks will have no references and can safely be deleted.

AST Blocks

Found in ast_block.h

typedef struct AST_block {
    block_t *block;
    block_type_t block_type;
    struct AST_block *next;
    struct AST_block *prev;
} AST_block_t;

Meant to be a tree that contains a generic block as well as that block's children and parent.

Current Implementation and Planned Implementation

Currently no implementation for AST_block in dev. Pull Request 802 contains:

 int run_ast_block(AST_block_t *block)

This runs the current AST_block and everything down the list from the AST_block. In the current state, AST_blocks are doubly linked lists instead of trees. With the modifications to branch_block, it will no longer need to be a doubly linked list. AST_blocks will be able to be represented as a singly linked list with any branches happening in branch blocks. Slight modifications will need to be made to run_ast_block, but since it operates recursively, it will not need to be doubly linked.

Custom Actions

Found in custom_action.h

typedef struct custom_action
{
    char *action_name;
    char *context;
    char *item;
    char *type;
    AST_block_t *head;
    UT_hash_handle hh;
} custom_action_t;

A struct for holding blocks and filling out all the information needed to identify and run a custom action. The custom_action_t struct is meant to be hashable (presumably into a complete list of custom actions in game). The context string is the kind of action that the custom action is (Ex. ITEM for an action that works on items).

Current Implementation and Planned Implementation

As mentioned previously, Pull Request 802 is working on a do_custom_action function that will run a custom action. There is already hash functionality with game, but it is needs to be properly integrated with the game module. There also needs to be WDL work on reading custom actions from WDL.

Plan for the Future

Functions for evaluating conditionals and the basics of do_custom_action need to be merged from Pull Request 802.

Branch blocks need to be cleaned up and made functional. This will allow the deletion of control_block_t and should allow basic functionality of all of the Custom Action code.

Functions for manipulating the AST_block as lists will also need to be added in the case that manipulations need to be done to existing AST_blocks.

• Searching, adding, and removing are basic examples.

The Custom_actions_t struct will need to be cleaned up a bit in order to properly integrate with the rest of chiventure.

• Depending on how integration occurs, items might need to be represented as item_t* instead of char* and context might be an enum instead of a char*.
• Other minor tweaks will almost certainly need to be made in order for custom actions to be integrated.

WDL updates will need to be made, so that custom actions can be added to games. Currently exists as issue #796

Generally functionality can also be added at any point.

• Adding more comparison types for conditionals
• Adding more actions to action blocks
• • This might need to be abstracted to modify things that aren't attributes.