This is the Mod System Tutorial "Mod" for Endless Dark, including examples and guides on how to hook the game and add your own content to it. Included within this mod is the Endless Dark Mod Guide, which outlines all possible in-game hooks and when they are called, along with examples for these hooks.

As the mod system is extended, this example mod will be used to show off different triggers and features available to the mod system, and will also include up to date versions of the mod guides on how to create new content.

=== ENDLESS DARK MOD GUIDE FOR 0.9.25 ===
Modding Endless Dark is simple - inside your profile directory (where profile.txt is located) is a "mods" directory. Any directory inside "mods" will attempt to load as a user mod. A mod's anatomy is simple - every .lua file within will be added as function to the global namespace that can be accessed at will. There are further over 100 specially-named functions, called "hooks", that are executed by the game logic at pre-determined intervals.

A quick example: In the "mods" folder, create a "test" directory, and place a single file within named "onload.lua":
mods/test/onload.lua

Have that file contain only a single line:
f_ed_log("SYSTEM: Hello, I am a test mod mod.", "info")

When the game is loaded, the "test" mod will load, add it to the global namespace, and execute the "onload" hook. You'll see a logging message in the game's console when pressing ~.

On Windows, mods go in: C:\Users\[username]\AppData\Roaming\EndlessDark\mods\
On Linux, mods go in  : ~/.local/share/EndlessDark/mods

== FUNCTIONS ==
Every .lua file in "mods" will be a named function in the game that can call each other or be called by other mods. The global namespace "usermods" will include a table of all mods and their functions. In the above example, usermods.test.onload is now an in-game function that can be called any time. Mods can call their own functions, other mods functions, or any function described in the ModAPI reference document.

== HOOKS ==
In addition to "onload", there are over 100 pre-defined points you can intercept and run your own code. The full set of existing hooks is below, including a short description of when they fire. If your mod has "onturnstart.lua", then on the start of the player's turn, your code inside "onturnstart.lua" will run. Your mod can also call any other functions you have defined, or any functions described in the "ModAPI" reference document. Suppose, for instance, you write your own function "myspecialfunction.lua", that simply makes the player emit a bark. You then have, in your "onturnstart.lua" function, a call to usermods.test.myspecialfunction - on turn start, your onturnstart hook is executed, which then will call myspecialfunction. Using this, almost any logic in the game can be intercepted and modified at will.

For even more complex modding, you will want to use the ModAPI reference, which is a list of in-game logic functions and their purposes.

Here is the list of all existing in-game hooks and when they fire. Again, any user mod that has a function with these names, will get executed at the point described:
HOOK NAME           WHEN IT RUNS
=========================================
onload               -- Runs only once, after the module has finished loading
ontick               -- Runs every frame, whether or not a game is in progress
onactive             -- Runs every frame, if a game is in progress and is active (there is no pending event, user is not in a menu)
onbotready           -- Runs when a custom custodian has finished loading (especially to inject personality into events)
onnewgame            -- Runs when a new game has begun
onbotchanged         -- Runs when the player changes the current bot during new game creation (ALSO triggers ondifficultychanged)
ondifficultychanged  -- Runs when the player changes difficulty during new game creation
onturnend            -- Runs when the turn has ended, after all other logic has processed
onturnstart          -- Runs when a new turn has started, after all other logic has processed
onnightmaretriggered -- Runs when the user WILL have a nightmare this turn (but may not have actually fired yet)
onhavingnightmare    -- Runs when the user is within a room-based nightmare (not a visual-only nightmare), including Airlock, Containment, Maze, and Nowhere
onfatiguegain        -- Runs when the player gains fatigue
onstressgain         -- Runs when the player gains stress
onpsychosisgain      -- Runs when the player gains psychosis
onfatigueloss        -- Runs when the player loses fatigue
onstressloss         -- Runs when the player loses stress
onpsychosisloss      -- Runs when the player loses psychosis (very rare)
onpressuregain       -- Runs when the player gains pressure
onpressureloss       -- Runs when the player loses pressure
onarcfinished        -- Runs when a story arc completes
ondeeploregained     -- Runs when deep lore is gained from the observation window
onmemoryunlocked     -- Runs when the player unlocks a memory (even if they already had unlocked it)
oninsanitygained     -- Evaluated when the player gains a new random insanity (Does not check certain event or task-specific insanities)
onrandomdamage       -- Runs when the Director damages a random system (Does not fire when certain events/tasks deliberately damage a specific system)
onpassengerdied      -- Runs when a passenger dies for any reason
onpodscontaminated   -- Runs when some or all pods become contaminated
onpodcondamage       -- Runs when a pod is damaged due to being contaminated
onairlocktoggled     -- Runs when the inner airlock is toggled
onbreakersurge       -- Runs when a breaker surge occurs
onpowersurge         -- Runs when a power surge occurs (random lock or overclock of all systems)
onshuffleinsanity    -- Runs when the player (generally ANNIE) shuffles insanities
onconsolesabotage    -- Runs when a console is sabotaged
onconsolerepair      -- Runs when a console is repaired
onsystemglitched     -- Runs when a system becomes randomly glitched (may not cover all cases)
onpermaglitched      -- Runs when a system becomes permanently glitched
onsystemdisabled     -- Runs when a system becomes disabled (may not cover all cases)
onsystemlocked       -- Runs when a system becomes locked (may not cover all cases)
onsystemoverclocked  -- Runs when a system becomes overclocked  (may not cover all cases)
onsystemhardened     -- Runs when a system becomes hardened  (may not cover all cases)
onsystemlosesoverclock -- Runs when a system loses overclocked  (may not cover all cases)
onsystemsabotaged    -- Runs when the player sabotages a system
onsystemrepaired     -- Runs when a system is repaired (NOT emergency repaired)
onsystemrepairfail   -- Runs when a repair fails
onsystemerepaired    -- Runs when a system is emergency repaired
onsystemerepairfail  -- Runs when an emergency repair fails  
onpowertoggle        -- Runs when power to a system is toggled (on or off)  
onbreakeropened      -- Runs when a breaker opens
onbreakerclosed      -- Runs when a breaker is closed
onbreakerdamaged     -- Runs when a breaker is damaged
onbreakerrepaired    -- Runs when a breaker is repaired
onbreakerreplaced    -- Runs when a breaker is replaced
onthrusterdamage     -- Runs when a thruster is damaged
onmemoryapply        -- Runs when the player gets their memory bonuses assigned at the start of a new game
onapplydilemma       -- Runs when the player's dilemma reward or penalty is applied at the start of a new game
onscaredofdoors      -- Runs when the player panics when interacting with a door due to Entamaphobia
ondirectorstart      -- Runs when the director (RNG function) starts
ondirectorend        -- Runs when the director (RNG function) ends
ongameloss           -- Runs when the game ends in a loss, but before endgame flag is set
ongamewin            -- Runs when the game ends in a win, but before endgame flag is set
oncooldownevent      -- Runs when the player is going to get a cooldown event due to having a bad time
onreactordamaged     -- Runs when the reactor takes damage
onobservationtoggled -- Runs when the observation window has been toggled to open or close
oncourseadjusted     -- Runs when the player adjusts course via navigation
onmemorycore         -- Runs when the player's memory core flags are set (which gives you equipment and room access)
onprofileattempt     -- Runs when the profile attempt count is incremented (basically when a story mode game is started)
onprofilekills       -- Runs when the profile kill count is incremented (when a passenger dies)
ontrolleyupdate      -- Runs when the list of Trolley Problem targets is updated
onkillorderupdate    -- Runs when the passenger kill order is updated (when a passenger dies due to events/etc)
onweathermade        -- Runs after the game has generated all space weather for the current game
onupdatepressure     -- Runs when the game evaluates how much pressure the player should currently have
onwelladjusted       -- Runs when ANNIE's special Well-Adjusted perk fires (to remove stress for being crazy)
onoddnumbers         -- Runs when the DISPARNUMEROPHOBIA insanity fires (to add psychosis for not having even parts)
onzonehazards        -- Runs when Shields or Navigation are taken offline by Gravity / EMP Zones
onpowerpenalty       -- Runs when the Reactor will get a stacking power penalty for being unrepaired for several turns
ondilemmarng         -- Runs when the game is about to roll to decide what Dilemmas to offer the player in story mode
oninsanityroll       -- Runs when the player is about to roll to determine if they gain a new insanity this turn
onnavigationrng      -- Runs when Navigation is about to roll to avoid weather hazards
onendgameloss        -- Runs when the player has just lost the game
onendgamevictory     -- Runs when the player has just won the game
oncircuitbreaker     -- Runs when the player's circuit breaker module has popped to avoid losing due to psychosis
oneventfired         -- Runs whenever an event is about to fire
onshipsaved          -- Runs before the game persists ship state to profile for the next game or when closing game
onshiprestored       -- Runs after the game applies damage to the ship from a previous game
onpartspurged        -- Runs after the player has lost parts due to going over the cap
onpersonalityshift   -- Runs when the player's actions have resulted in a personality shift
onroomchanged        -- Runs when the player has moved from one room to another
onbetrayal           -- Runs when the robot is about to betray the player by doing an action other than the one requested
onpanicking          -- Runs on EVERY FRAME if the robot is currently panicking
ondrawcomplete       -- Runs on EVERY FRAME when all drawing operations are done (Mod drawing ops can only happen within draw hooks)
onloselingering      -- Runs when the player loses lingering stress debuffs
ongainlingering      -- Runs when the player gains or upgrades lingering stress debuffs
onplayerreset        -- Runs when the player's state was reset (such as during the tutorial)
ontemporaryeffect    -- Runs when the player has gained a (non-insanity) temporary effect (generally from events)
onpermanenteffect    -- Runs when the player has gained a (non-insanity) permanent effect (generally from events)
onminiarcscheduled   -- Runs when the player has scheduled a mini-arc
ongazefishtank       -- Runs when the player gazes at their fish tank
onlockertap          -- Runs when the player taps on a locker
onlockerclose        -- Runs when the player closes a locker
onlockeropen         -- Runs when the player opens a locker
onlockersearch       -- Runs when the player searches a locker, regardless if it is for a story or not
ondoorunwedge        -- Runs when the player un-wedges a wedged door
ongaze               -- Runs when the player gazes into the observation window




















== SPECIAL FUNCTIONS ==
There are also special function files for creating custom custodians or overriding the cost of actions in the game. These are:

loadbot              -- Contains the template file for a custom custodian
actions              -- Contains a table that will override in-game action costs with user-defined costs

== INFO.TXT ==
INFO.TXT is maintained as a simple file to name your mod, put your name in it, along with what version of the game it was made for, and what version of the mod you are using.

== NAMING CONVENTIONS ==
MODNAME is always forced to be lower-case, regardless of what the mod's directory is named. It must contain only the alpha characters a-z,A-Z.