Created template scripts (markdown)

template-scripts.md

@@ -0,0 +1,95 @@
+If you have multiple scripts that are very similar you can split common functionality into a single script that gets included into all scripts that share this functionality.
+
+The following assumes you want to create a number of _awesome_ entities, all sharing an _awesomecommon_ base script.
+
+# OSE version
+
+
+### awesomecommon.lua
+```
+if not v then v = {} end
+if not AQUARIA_VERSION then dofile("scripts/entities/entityinclude.lua") end
+
+function v.commonInit(me, tex, scale) -- some extra parameters, optional
+    setupEntity(me, tex)
+    entity_scale(me, scale, scale)
+end
+
+function v.commonUpdate(me, dt)
+    -- do common stuff
+end
+```
+
+### awesome1.lua
+
+```
+dofile("scripts/awesomecommon.lua")
+
+function init(me)
+    v.commonInit(me, "awesome1", 42)
+    -- individual init here...
+end
+
+function update(me, dt)
+    v.commonUpdate(me, dt)
+    -- individual update things here...
+end
+```
+
+Note that the `dofile()` will load a script from your mod if the file exists, and if no such file can be found, it tries to load the file from the vanilla _scripts_ directory. If it still can't be found there will be an [[error|common-errors]].
+
+# Old script interface
+
+For reference, the pre-OSE way of doing the same is as follows:
+
+
+### awesomecommon.lua
+```
+dofile("scripts/entities/entityinclude.lua")
+
+function commonInit(me, tex, scale) -- some extra parameters, optional
+    setupEntity(me, tex)
+    entity_scale(me, scale, scale)
+end
+
+function commonUpdate(me, dt)
+    -- do common stuff
+end
+```
+
+### awesome1.lua
+
+```
+dofile(appendUserDataPath("_mods/myMod/scripts/awesomecommon.lua"))
+
+function init(me)
+    commonInit(me, "awesome1", 42)
+    -- individual init here...
+end
+
+function update(me, dt)
+    commonUpdate(me, dt)
+    -- individual update things here...
+end
+```
+
+Note that you really need to use this:
+```
+dofile(appendUserDataPath("_mods/myMod/scripts/awesomecommon.lua"))
+```
+
+instead of the more intuitive
+
+```
+dofile("_mods/myMod/scripts/awesomecommon.lua")
+```
+
+Why? The old version does not treat mod scripts paths specially. In the Windows version the second, simpler variant does work, but will not be able to locate the file on Linux or Mac. Therefore you must use the first variant, which is longer but guarantees that your script is loaded regardless of the user's operating system.
+
+And yes, the path _must_ contain your mod name. If you change the folder name of your mod, you must update _all_ scripts.
+
+If you want to reference an existing vanilla script, leave the mod path away. Like this:
+
+```
+dofile("scripts/awesomecommon.lua")
+```