View source for Tutorial:Mod Script File Management

In programming, keeping the majority of code in the same area is generally viewed as a bad practice. It can reduce the efficiency of moving through files, results in a project being harder to read, and overall makes the coding experience more difficult.

In PMDO Modding, the primary area this problem appears when creating lua scripts for ground maps. Figuring out a method to manage ground map files is important.

== Accessing Different Script Files ==
The core enabler of file organization is the ability to reference the contents of different files in lua.

The <code>require</code> keyword may be used to access files by specifying where they can found. This keyword starts relative to PMDO's base <code>script</code> folder - and, in the case of a mod, that mod's based <code>script</code> folder.

Using the require keyword makes all of the global variables (variables not defined prefixed by <code>local</code>) found in the other file accessible by the file that called that keyword. Because functions in Lua are stored by writting them to a table to be called later, we can reference a global table and any of its functions. So, with all functions defined to a global table, that table is now able to have all of its functions called from a foreign file.

Scripts that are added specifically by a mod should be placed in the subfolder of scripts named after that mod's namespace. For example, a mod with the namespace of <code>test_mod</code> should have all of its implemented scripts put into that folder. This is to avoid collision with the names of other mod's files.

=== Example ===
Suppose we have the file <code>code.lua</code> placed within the <code>test_mod</code> folder with the contents:
 <nowiki>Code = {}

function Code.go()
      -- imagine this function does something
end</nowiki>

Say we have some other script file that we want to call the function <code>Code.go()</code>, which is present inside of <code>code.lua</code>.

It is possible to do so by writting this in that file:

 <nowiki>require 'test_mod.code'

Code.go()</nowiki>

When that file is loaded, the </code>Code.go()</code> function will be immediately called.

== Structuring Ground Script Files ==
A common area that must be organized and structured in mods is the script files for ground maps. These often require tons of scripting for things such as cutscenes, ground NPC dialogue, shop access, and checking state. For most modders, splitting the ground script folder up into different subfolders is the most useful.

There are two different primary file structures that have been found to be useful.

=== Section Splitting ===
Ground map scripts are split on "chapters", or what current section of the story the player will be in when they can encounter those scripts. 

This is typically done when a mod is designed on a chapter-to-chapter basis, and will have new chapters gradually added to it over time. This naturally splits the code into the parts of each chapter, which will be worked on simultaneously.

=== Purpose Splitting ===
Ground map scripts are split depending on the purpose that each piece of code serves. This is useful for developers who prefer to work on different sections of the code rather than directly on story sections.

One schema for splitting the files:
* <code>init.lua</code> - The primary driver and manager of being on the ground map. This mostly calls all of the functions as they are needed, and does activities such as checking for state.
* Interacts - The interactions from talking to NPCS on the map. These functions are directly called in each of the base action functions, and are passed the activator and activated character.
* Cutscenes - Cutscenes that will be played as needed. Often can be passed characters and other variables from the init.
* State - Manages the visible state of the ground map.

[[Category:Tutorial]]