Overrides

Shiva has five levels of customization. You never need to edit core files. From lightest to most powerful:

Level 1: Config

Change behavior through the module's config.lua. No code needed.

-- resources/[shiva]/shiva-economy/config.lua
Config.startingCash = 1000
Config.allowNegativeBalance = false

Best for: Tuning numbers, enabling/disabling features, changing defaults.

---

Level 2: Locale Overrides

Override any string in any module without touching the module:

-- resources/[shiva]/shiva-player/shared/locales/en.lua (DO NOT edit this)

Instead, create resources/my-overrides/locales/shiva-player/en.lua:

return {
    ['player.welcome'] = 'Welcome to My Server, {name}!',
}

Best for: Custom language, renaming UI strings, branding.

---

Level 3: Event Hooks

Hook into events to run additional logic without replacing anything:

-- my-module/server/init.lua
function M.start(container)
    local bus = container:make('IEventBus')

    bus:on('economy:moneyAdded', function(event)
        -- log to external system, send Discord webhook, etc.
        Discord.log('💰 Player %d received $%d', event.playerId, event.amount)
    end)
end

Best for: Side effects, logging, analytics, Discord integration.

---

Level 4: Plugins

Modules can expose plugin hooks — named extension points that run your code inside the module's logic:

-- shiva-inventory declares a plugin hook:
-- 'inventory:beforeAddItem' → return false to cancel

-- Your module hooks it:
container:bind('inventory:beforeAddItem', function(ctx)
    if ctx.item == 'illegal_item' and not ctx.player:hasJob('police') then
        return false  -- cancels the item add
    end
    return true
end)

Best for: Modifying behavior mid-flow without replacing the whole service.

---

Level 5: Contract Replacement

Replace an entire module's implementation by providing the same contract:

-- my-economy/manifest.lua
return {
    name = 'my-economy',
    provides = { 'IEconomy' },
    requires = { 'IPlayer' },
}

Disable shiva-economy in server.cfg, enable my-economy. The container will use your implementation everywhere.

Best for: Complete rewrites, integrating third-party economy systems.

---

Which Level Should I Use?

Need	Level
Change a config value	1
Rename a UI string	2
React to something that happens	3
Modify behavior mid-flow	4
Replace a whole system	5

Start at the lowest level that solves your problem.