A library to make it easy for developers to add new Gods/NPC Gods/NPCs. It does nothing by itself. You should only install it if another mod requires it, or if you will be using this library to create Gods.

[!IMPORTANT] Currently, this library only supports adding in Olympian Gods eg. Zeus and NPC-type Gods eg. Hermes.
NPC Type means that they will not fill up the MetGods table during a run - meaning you can have Zeus, Aphrodite, Hera, Hestia and meet Hermes and Your God.

• I would like to add Spells and proper NPC's such as Dionysus/Athena/Arachne during runs, and Hub NPCS such as Hecate/Hypnos.
  However, there are a lot of functions that are hard-coded to SpellDrop, and I am unsure about the state of adding 3D models.

[!NOTE] If there are any requests, anything I missed, or anything working incorrectly, post an issue, or create a help thread in the Hades Modding Discord.

Developer Documentation

1. Create a dependency in manifest.json (if testing locally) by adding "zannc-GodsAPI-1.0.0" and in thunderstore.toml by adding zannc-GodsAPI = "1.0.0" if publishing the mod by adding to respective files.

2. In main.lua, add:

   --@module 'zannc-GodsAPI'
   gods = mods['zannc-GodsAPI']
   

   So that it looks like this as an example:

   _PLUGIN = PLUGIN
   game = rom.game
   
   --@module 'SGG_Modding-ModUtil'
   modutil = mods["SGG_Modding-ModUtil"]
   --@module 'SGG_Modding-ReLoad'
   reload = mods["SGG_Modding-ReLoad"]
   --@module 'SGG_Modding-SJSON'
   sjson = mods["SGG_Modding-SJSON"]
   --@module 'zannc-GodsAPI'
   gods = mods["zannc-GodsAPI"]
   

3. In a file called through on_ready() or in modutil.once_loaded.game() (or directly in those), call gods.Initialize(_PLUGIN.guid). This will allow for the API to use your plugin guid for SJSON hooks for Portraits/Icons.

4. To create a god, you must call gods.InitializeGod(params), followed by gods.CreateOlympianSJSONData(sjsonData) and provide the required paramaters / sjson paramaters.
   

Parameters

While this is not a definitive list, these are the most common that will need to be changed.

• params (table) - A set of options to create the name, colour, text, gender, spawn sound etc.

  • godName (string) (required) - The name of the God | eg "Ares", "Zeus" etc.
  • godType (string) (required) - The type of God | eg "god" or "npcgod" (God = Zeus, NPC = Hermes)
  • SpawnLikeHermes (boolean) (optional) - Commonly used with a NPCGod, which creates requirements for the god to spawn, just like Hermes.
  Optional Parameters

  • GameStateRequirements (table)
  • Gender (string)
  • LoadPackages (table)
  • FlavorTextIds (table)
  • SFX_Portrait (string)
  • UpgradeSelectedSound (string)
  • WeaponUpgrades (table)
  • Traits (table)

  Colours

  • Color (table)
  • NarrativeTextColor (table)
  • NameplateSpeakerNameColor (table)
  • NameplateDescriptionColor (table)
  • LightingColor (table)
  • LootColor (table)
  • SubtitleColor (table)

  Dialogue/Text

  • FirstSpawnVoiceLines (table)
  • OnSpawnVoiceLines (table)
  • UpgradeMenuOpenVoiceLines (table)
  • DuoPickupTextLines (table)
  • InteractTextLineSets (table)
  • BoughtTextLines (table)
  • BoughtTextLinesRequirements (table)
  • RejectionTextLines (table)
  • RejectionVoiceLines (table)
  • MakeUpTextLines (table)
  • GiftTextLineSets (table)
  • GiftGivenVoiceLines (table)
  • FullSuperActivatedVoiceLines (table)
  • DeathTauntVoiceLines (table)
  • RarityUpgradeVoiceLines (table)
  • BlindBoxOpenedVoiceLines (table)

SJSON Paramaters

If you wish to add SJSON content, such as the boon drop icons, door preview icons or portraits, you must call gods.CreateOlympianSJSONData(sjsonData)

• sjsonData (table) - A set of options to create the name, colour, text, gender, spawn sound etc.

  • godName (string) (required) - The name of the God | eg "Ares", "Zeus" etc.
  • godType (string) (required) - The type of God | eg "god" or "npcgod" (God = Zeus, NPC = Hermes)
  • skipBoonSelectSymbol (boolean) (optional) - If there is already a Boon Select Symbol (In upgrade screen), you can pass this to skip the creation of one.
  Optional Parameters

  • iconSpinPath (string) - The animation of the physical boon drop.
  • previewPath (string) - The icon to display on doors.
  • colorA (table) - The colours of the physical boon drop
  • colorB (table)
  • colorC (table)
  • portraitData (table) (optional)
    • skipNeutralPortrait (boolean) (optional) - If there is already a neutral portrait for the character in the game.
    • AnnoyedPortraitFilePath (string)
    • DialogueEntrance (boolean) (optional) - If you wish to create animations during a portrait entrance.
      • RedStart (float) - The starting colour for the animations. eg. 1.0
      • StartGreen (float)
      • StartBlue (float)
      • EndRed (float) - The starting colour for the animations. eg. 0.1
      • EndGreen (float)
      • EndBlue (float)

For a full list of parameters, please refer to the PARAMS.md file.

Checking Implementation

If you need to check if the God you created is currently registered, or need to use an if statement to check if a god is enabled/disabled per config, you can use gods.IsGodRegistered("GODNAME", debug) - returning true or false. If you pass in debug (true), it will return a warning print for confirmation of creation.

Examples

This will add a new God: Artemis with the internal name ArtemisUpgrade.

gods.Initialize(_PLUGIN.guid)

gods.InitializeGod({
    godName = "Artemis",
    godType = "GOD",
    Gender = "F",
    LoadPackages = { "Artemis" },
    FlavorTextIds = { "ArtemisUpgrade_FlavorText01", "ArtemisUpgrade_FlavorText02", "ArtemisUpgrade_FlavorText03" },

    SpawnSound = "/SFX/ArtemisBoonArrow",
    PortraitEnterSound = "/SFX/ArtemisBoonArrow",

    WeaponUpgrades = game.EnemyData.NPC_Artemis_Field_01.WeaponUpgrades,
    Traits = game.EnemyData.NPC_Artemis_Field_01.Traits,

    Color = { 91, 255, 100, 255 },
    LightingColor = { 210, 255, 97, 190 },
    LootColor = { 110, 255, 0, 180 },
    SubtitleColor = Color.ArtemisVoice,
})

gods.CreateOlympianSJSONData({
    godName = "Artemis",
    godType = "god",
    skipBoonSelectSymbol = true,
    iconSpinPath = "Items\\Loot\\Boon\\ArtemisIconSpin\\ArtemisIconSpin",
    previewPath = "Items\\Loot\\Boon\\ArtemisIconSpin\\ArtemisPreview",
    colorA = { Red = 0.42, Green = 0.62, Blue = 0.21 },
    colorB = { Red = 0.35, Green = 0.51, Blue = 0.12 },
    colorC = { Red = 0.23, Green = 0.57, Blue = 0.31 },
    portraitData = {
        skipNeutralPortrait = true,
    },
})

This will add a new NPC God: Athena with the internal name AthenaUpgrade, and function like Hermes does.

gods.Initialize(_PLUGIN.guid)

gods.InitializeGod({
	godName = "Athena",
	godType = "npcGOD",
	SpawnLikeHermes = true,

	Gender = "F",
	LoadPackages = { "Athena" },
	FlavorTextIds = { "AthenaUpgrade_FlavorText01", "AthenaUpgrade_FlavorText02", "AthenaUpgrade_FlavorText03" },

	Traits = game.EnemyData.NPC_Athena_01.Traits,

    SubtitleColor = Color.AthenaVoice,
	Color = { 91, 255, 100, 255 },
	LootColor = { 175, 157, 255, 255 },
	LightingColor = { 175, 157, 255, 255 },
})

gods.CreateOlympianSJSONData({
	godName = "Athena",
	godType = "npcGOD",
	skipBoonSelectSymbol = true,

	iconSpinPath = "Items\\Loot\\Boon\\AthenaIconSpin\\AthenaIconSpin",
	previewPath = "Items\\Loot\\Boon\\AthenaIconSpin\\AthenaPreview",
	colorA = { Red = 0.76, Green = 0.64, Blue = 0.16 },
	colorB = { Red = 0.68, Green = 0.57, Blue = 0.12 },
	colorC = { Red = 0.60, Green = 0.51, Blue = 0.19 },
	portraitData = {
		NeutralPortraitFilePath = "Portraits\\Portrait1",
		AnnoyedPortraitFilePath = "Portraits\\Portrait2",
    
        DialogueAnimations = {
            DialogueEntrance = {
                RedStart = 1.0,
                GreenStart =  0.7,
                BlueStart = 0.1,
                RedEnd = 0.3,
                GreenEnd = 0.4,
                BlueEnd = 1.0,
            }

            DialogueEntranceStreaks = {
                RedStart = 0.5,
                GreenStart =  0.8,
                BlueStart = 0.3,
                RedEnd = 0.2,
                GreenEnd = 0.1,
                BlueEnd = 0.1,
            }

            DialogueEntranceParticles = {
                RedStart = 0.5,
                GreenStart =  0.8,
                BlueStart = 0.3,
                RedEnd = 0.2,
                GreenEnd = 0.1,
                BlueEnd = 0.1,
            }

            DialogueEntranceParticleBurst = {
                RedStart = 0.5,
                GreenStart =  0.8,
                BlueStart = 0.3,
                RedEnd = 0.2,
                GreenEnd = 0.1,
                BlueEnd = 0.1,
            }
        }
	},
})

Changelog

Unreleased

2.1.5 - 2026-01-26

• DEV: Change PLUGIN to _PLUGIN

2.1.4 - 2026-01-21

• Added frameScale to allow for scaling of custom frames in CreateCustomRarity.

2.1.3 - 2026-01-04

• DEV: Check if GiftData exists before creating it.
• DEV: Fix issue where most codex entries were generating an 'Offerings' button.
• DEV: Added boonPosition for Traits.
• Added new paramater for Boon icon scaling: boonIconScale.
• Documentation update for characterName and addToExistingGod stating it does not add to a god automatically.

2.1.2 - 2025-12-28

• FIX: Custom boons were not being added to codex/ponymenu unless it is added to a new custom god.

2.1.1 - 2025-12-28

• FIX: issue where trait index's weren't being created for default game gods (Selene for some reason).

2.1.0 - 2025-12-22

• Added customGiftData to CreateKeepsake
• Fix internalKeepsakeName.
• Fix RarityLevel Multiplier.
• Added ExtraFields to CreateKeepsake because I missed it somehow.
• Fixed Min/MaxRequirements for Keepsakes.
• Added new function, CreateCustomRarity to be used with CreateBoon.
• Update customStatLine to support multiple statlines.
• Slight ReadME/Dev/Params update.

2.0.7 - 2025-12-10

• Fix ConsumableData issue with Shop of Hermes?
• Fix ConsumableData maximum spawn chance in shops to adhere to normnal spawn chance of god.

2.0.6 - 2025-12-09

• Add ExtraFields param to CreateGod.
• Remove Dash from Shop .. godName due to it not adhering to StoreLogic discounts (Travel Deal).
• Added option for SpawnLikeHermes to be a table containing maximumSpawns, with a value of 1 being 2 natural spawns maximum per run.
• Change SurfaceIcon for boons to be the IconPreview of boons.
• Small def/params update.
• Added OverlayAnim to PortraitData.

2.0.5 - 2025-12-08

• Fix issue with NPC God spawning in Shops.
• Naming Convention for Shop var in NPC.
• Fix InheritFrom nil check in CreateBoon.
• Relaxed need to define plugin.guid for trait requirements, it will try to fall back to _PLUGIN.guid-internalboonname, or else throw a warning and remove it from the list.
• Added customGUID to addToExistingGod to allow for insertions into god not using your GUID.
• Allow for godtype = god and still limit spawns to function like hermes
• Touched up on docs.
• DEV: Added Boon Population for EnemyData after game loads, makes it easier to add boons to NPCs too.
• Hopefully fixed issue which was causing NPC/Spawn Limited gods to constantly appear.

2.0.4 - 2025-12-02

• Slight change to defs.
• Update README.

2.0.3 - 2025-12-01

2.0.2 - 2025-12-01

• Fix addToExistingGod.

2.0.1 - 2025-12-01

• Add missing GodLoot, usefule for other mods to check if GodLoot or not.

2.0.0 - 2025-12-01

• Add Data Inheritence to functions // cuts down on params (though can still be changed)
• Use InheritFrom in creation of Boons instead of isLegendary // Elements
• No longer need to pass in _PLUGIN.guid.
• Append _PLUGIN.guid to Gods/Keepsakes/Boons to allow for multiple people to create Gods/Keepsakes/Boons of same name.
• No longer need to define FlavourText if you have created Descriptions for them, though it still remains a param if you want to reuse any.

1.0.9 - 2025-11-28

• Changed how RarityLevels can be passed in (you can now pass in Multipliers/tables or just a number)
• Added Default Boon Icon and Keepsake Icon.
• Fixed Disappearing Icons?
• Added params to Keepsake and Boons to create CustomStatLines
• Fix Codex Population
• Fix TraitSortOrder being populated as an empty table
• Fix Boon Inheritance
• Fix Portrait Inheritance
• Fix Slotted Trait inserts
• Added ability to create custom text for codex & images.

1.0.8 - 2025-11-19

• Added iconPathOverrides (table) to CreateOlympianSJSONData allow for reuse of any Icons in the game.
• Added portraitPathOverrides (table) to CreateOlympianSJSONData allow for reuse of any Portraits in the game.
• Added iconPathOverrides (table) to CreateKeepsake allow for reuse of any Icons in the game.
• Added reuseBaseIcons (bool) to CreateBoon allow for reuse of any Icons in the game.
• Fix Codex "Entity Name".
• More info in DEV.
• DEV: Reworked iconPathing - and cleanIconPath func, no longer combines automatically but does a check and combines if needed

1.0.7 - 2025-11-18

• Added addToExistingGod paramater.
• Moved code around to do traitdict and traitsortorder to work after all mods loaded.

1.0.6 - 2025-11-17

• Readme update.

1.0.5 - 2025-11-17

• Add Default Values to Keepsake Description/Display
• Slight updates to Params/Dev.
• Added basic dirty work for Traits/Boons.

1.0.4 - 2025-11-11

• Fixed Upgrade Choice Screen Text Boons of GodName
• Fixed Icon Pathing being broken
• Added Scale and OffsetX/Y to portraits
• Added optional BoonDrop frames - so you dont have to do 50 frames to get the icon spin
• DEV: Cleaned up code

1.0.3 - 2025-11-10

• Added support for Keepsakes.
• Add check for paths to remove _PLUGIN.guid if passed in the file paths.
• Added missed flavour text for SJSON.
• Defs.
• Update ReadME.

1.0.2 - 2025-11-09

• No longer need to call gods.Initialize(), just pass the _PLUGIN.guid into SJSON creation.

1.0.1 - 2025-11-07

• Update ReadME/Params

1.0.0 - 2025-11-07

• Initial Release.