Refactor Action Definitions And Create Examples With JSON Logic Prerequisites

by ADMIN 78 views

Introduction

As part of the ongoing effort to integrate JSON Logic into action prerequisites, it is essential to update existing action definition JSON files to use the new JSON Logic format for any prerequisites they have. Additionally, new examples need to be created to demonstrate non-trivial JSON Logic prerequisites. This ticket outlines the necessary steps to refactor action definitions and create examples with JSON Logic prerequisites.

Prerequisites

Before embarking on this task, it is crucial to understand the JSON Logic format and the JsonLogicEvaluationContext structure. The JsonLogicEvaluationContext provides a context for evaluating JSON Logic expressions, which includes the actor, target, and components. This knowledge is necessary to write correct var paths in the JSON Logic objects.

Tasks

Identify Existing Prerequisites

The first step is to review all existing action definition JSON files and identify any that currently have a non-empty prerequisites array using the old ConditionObject format. This involves searching for action definition files such as action_attack.json, action_open.json, action_eat.json, etc.

Convert Existing Prerequisites

For each identified action definition, the intent of the old ConditionObject needs to be analyzed based on the condition_type, details, and negate. This logic then needs to be translated into a valid JSON Logic object that achieves the same result using the available JsonLogicEvaluationContext.

Component Existence Check

A component existence check can be represented in JSON Logic as follows:

{"!!": {"var": "actor.components.Stamina"}} (double negation checks for truthiness)
or
{"!==": [{"var": "actor.components.Stamina"}, null]}

Component Property Check

A component property check can be represented in JSON Logic as follows:

{">": [{"var": "actor.components.Stamina.current"}, 0]}

Logical AND/OR

Logical AND/OR operations can be represented in JSON Logic using the and and or operators:

{"and": [...]}
or
{"or": [...]}

Replace Old ConditionObject Array Elements

The old ConditionObject array elements need to be replaced with the new JSON Logic objects in the prerequisites array.

Create New Examples

New or augmented action definitions need to be created to demonstrate clear, non-trivial prerequisites using JSON Logic. Examples should cover the following scenarios:

Checking if the Actor has a Specific Component and a Property within that Component Meets a Condition

{
  "prerequisites": [
    {
      "and": [
        {"var": "actor.components.Stamina"},
        {">": [{"var": "actor.components.Stamina.current"}, 10]}
      ]
    }
  ]
}

Checking if the Target Lacks a Specific Component

{
  "prerequisites": [
    {"!": {"var": "target.components.Ethereal"}}
  ]
}

Combining Actor and Target Checks using AND

{
  "prerequisites": [
    {
      "and": [
        {"var": "actor.components.Mana"},
        {">": [{"var": "actor.components.Mana"}, 5]},
        {"!": {"var": "target.components.MagicImmunity"}}
      ]
    }
  ]
}

Optional: Checking a Global State Variable if Applicable

If the context allows, checking a global state variable can be represented in JSON Logic as follows:

{"var": "globalStateVariable"}

Add Comments

Explanatory comments need to be added within the JSON examples to clarify the intent of the JSON Logic rules.

Validate Examples

All modified and new action definition files need to be validated against the updated action-definition.schema.json using the validation tooling (see Ticket 3.6).

Acceptance Criteria

  • All existing action definitions previously using the old prerequisites format are updated to use valid JSON Logic syntax reflecting the original intent.
  • At least 2-3 clear examples of action definitions with non-trivial JSON Logic prerequisites are created and added to the project's data/examples.
  • Examples cover common scenarios like component existence checks, property value checks, negation, and logical combinations (AND/OR).
  • All updated/new action definition files successfully validate against the modified action-definition.schema.json.

Dependencies

  • Ticket 3.1: action-definition.schema.json must be updated first.
  • Understanding of the JsonLogicEvaluationContext structure (Ticket 3.2) is needed to write correct var paths.

Estimate

The estimate for this task is medium, requiring careful analysis, conversion, and creation of JSON data.

Introduction

As part of the ongoing effort to integrate JSON Logic into action prerequisites, it is essential to update existing action definition JSON files to use the new JSON Logic format for any prerequisites they have. Additionally, new examples need to be created to demonstrate non-trivial JSON Logic prerequisites. This Q&A article aims to provide answers to common questions related to refactoring action definitions and creating examples with JSON Logic prerequisites.

Q: What is JSON Logic, and why is it being integrated into action prerequisites?

A: JSON Logic is a lightweight, JSON-based logic language that allows for the expression of complex logic rules in a simple and readable format. It is being integrated into action prerequisites to provide a more flexible and powerful way of defining prerequisites for actions.

Q: What are the benefits of using JSON Logic in action prerequisites?

A: The benefits of using JSON Logic in action prerequisites include:

  • Improved flexibility: JSON Logic allows for the expression of complex logic rules in a simple and readable format.
  • Increased power: JSON Logic provides a more powerful way of defining prerequisites for actions.
  • Simplified maintenance: JSON Logic makes it easier to maintain and update action prerequisites.

Q: How do I identify existing prerequisites in action definition JSON files?

A: To identify existing prerequisites in action definition JSON files, you need to review the files and look for any non-empty prerequisites arrays using the old ConditionObject format.

Q: How do I convert existing prerequisites to JSON Logic?

A: To convert existing prerequisites to JSON Logic, you need to analyze the intent of the old ConditionObject based on the condition_type, details, and negate. You then need to translate this logic into a valid JSON Logic object that achieves the same result using the available JsonLogicEvaluationContext.

Q: What are some common scenarios that I should cover in my new examples?

A: Some common scenarios that you should cover in your new examples include:

  • Component existence checks
  • Property value checks
  • Negation
  • Logical combinations (AND/OR)

Q: How do I add comments to my JSON examples to clarify the intent of the JSON Logic rules?

A: To add comments to your JSON examples, you can use the // or /* */ syntax to add comments within the JSON file.

Q: How do I validate my updated and new action definition files against the updated action-definition.schema.json?

A: To validate your updated and new action definition files against the updated action-definition.schema.json, you can use the validation tooling (see Ticket 3.6).

Q: What are the acceptance criteria for this task?

A: The acceptance criteria for this task include:

  • All existing action definitions previously using the old prerequisites format are updated to use valid JSON Logic syntax reflecting the original intent.
  • At least 2-3 clear examples of action definitions with non-trivial JSON Logic prerequisites are created and added to the project's data/examples.
  • Examples cover common scenarios like component existence checks, property value checks, negation, and logical combinations (AND/OR).
  • All updated/new action definition files successfully validate against the modified action-definition.schema.json.

Q: What are the dependencies for this task?

A: The dependencies for this task include:

  • 3.1: action-definition.schema.json must be updated first.
  • Understanding of the JsonLogicEvaluationContext structure (Ticket 3.2) is needed to write correct var paths.

Q: What is the estimate for this task?

A: The estimate for this task is medium, requiring careful analysis, conversion, and creation of JSON data.