LuaWorldStateSystem

LuaWorldStateSystem is a versatile Lua library designed to manage the state of a game world, including player attributes, relationships, and various game events triggered by specific conditions. This system provides a robust framework for designing dynamic game experiences where player actions influence the game world and its narrative.

Features

• Player Data Management: Efficiently manage player attributes, relationships with NPCs, and key lore events that shape the game's narrative.

• Event Management: Define custom game events triggered by specific player conditions, such as reaching attribute thresholds, achieving milestones, or interacting with NPCs.

• Flexible Condition Evaluation: Evaluate a variety of conditions, including player attributes, relationship levels, and lore events, to determine when events should be triggered.

• Debugging Support: Enable debug mode to track changes in player data and event triggers for testing and troubleshooting.

Installation

1. Clone the LuaWorldStateSystem repository to your project directory:

   git clone https://gist.github.com/f321a4be0696339514bd7053b8781e68.git LuaWorldStateSystem

2. Import the necessary modules into your Lua project:

   local GamePlayerData = require("LuaWorldStateSystem.PlayerData")
   local GameEventManager = require("LuaWorldStateSystem.EventManager")

3. Start using the system to manage player data and events in your game.

Usage

Player Data Management

-- Create a new player with initial attributes, relationships, and loreKeys
local player = GamePlayerData.new({
    strength = 3,
    dexterity = 1,
    constitution = 1,
    intelligence = 0,
    wisdom = 0,
    charisma = 2,
    generosity = 0,
    honesty = 0,
}, {
    Alex = 2,
    Jordan = -2,
}, {
    discoveredSecretCave = false,
})

-- Update player attributes and relationships
player:update_attribute("generosity", 5)
player:update_relationship("Alex", 3)

-- Set a lore key
player:set_lore_key("discoveredSecretCave", true)

Event Management

-- Define a new event
-- Define a new event using EventManager's CreateEvent function
local event1 = EventManager.CreateEvent(
    "event1",
    { { type = "attribute", name = "strength", value = 3 } },
    {
        function(playerData)
            print("Event1 Triggered: Strength condition met.")
            -- Increase player's charisma as a reward
            playerData:update_attribute("charisma", 1)
        end
    },
    {}
)
event1.autoTrigger = true -- Automatically trigger the event when conditions are met (default: true)

-- Add the newly created event to the EventManager
EventManager:add_event(event1)
-- Alternatively, you can directly add an event to the EventManager
local event2 = EventManager:add_event({
    name = "event2",
    conditions = { { type = "attribute", name = "charisma", value = 3 } },
    actions = {
        function(playerData)
            print("Event2 Triggered: Charisma condition met.")
            -- Increase player's generosity as a reward
            playerData:update_attribute("generosity", 1)
        end
    },
    linkedEvents = {}
})
event2.autoTrigger = true
table.insert(event1.linkedEvents, event2:id())

-- Simulate game logic where player discovers a secret cave, affecting loreKeys
player:set_lore_key("discoveredSecretCave", true)

-- If necessary, directly activate a specific event based on gameplay events
EventManager.activate_event(event1:id())

-- In a game loop or specific update function, continuously check for potential events
local potentialEvents = EventManager.get_potential_events(player)
print("Potential events based on the current state: ", #potentialEvents)
for _, event in ipairs(potentialEvents) do
    print(string.format("Event: %s - id: %s", event.name, event.id))
end


-- Check and trigger events, assuming the game has progressed and conditions might be met
EventManager.check_events(player, true)

Output:

Change event: loreKey discoveredSecretCave changed from false to true
Potential events based on the current state: 1
Event: event1 - id: fcb57462-4854-48ec-a73f-0ec71
Event1 Triggered: Strength condition met.
Change event: attribute charisma changed from 2 to 3
Event2 Triggered: Charisma condition met.
Change event: attribute generosity changed from 0 to 1

• event1 was triggered because the player's strength condition was met.
• event2 was subsequently triggered because its condition (charisma reaching 3) was met after event1 triggered, thanks to the linkage established between the events.

Debug mode activated for the player, allowing us to see the changes in attributes (charisma and generosity) and the lore key (discoveredSecretCave) as they occurred during test.