Skip to content

Getting Started

Jump to bottom
Proddy edited this page May 10, 2023 · 6 revisions

Configuring a Simpsons: Hit and Run mod

1) Configuring metadata

The first step is configuring the Custom Files hack. To do this, in the Miscellaneous header of your mod's Meta.ini, you need to add a RequiredHack line. In this same file is where you add the required credits:

[Miscellaneous]
Title=Lua P3D Lib Example
InternalName=LuaP3DLibExample
Description=A dummy mod to show LuaP3DLib
Version=1
; The following line enables the Custoim Files hack in your mod:
RequiredHack=CustomFiles

; The following lines are the author credits:
[Author]
Name=Proddy
Website=https://github.com/Hampo/LuaP3DLib
Notes=P3D Class System
Group=LuaP3DLib

[Author]
Name=EnAppelsin
Website=https://github.com/EnAppelsin
Notes=Original P3D Lua idea
Group=LuaP3DLib

[Author]
Name=Lucas Cardellini
Website=https://lucasstuff.com/
Notes=P3D Chunk Structures
Group=LuaP3DLib

2) Adding the LuaP3DLib files

Now that you have a base mod, the next step is to add the LuaP3DLib files. In the root directory, create a folder called Resources, and then another folder called lib inside of that one. Download P3D.zip from the latest release and extract to the lib folder. You should end up with a file at ModPath/Resources/lib/P3D2.lua and a directory at ModPath/Resources/lib/P3DChunks.

Note: If you want to save some space, and minorly improve efficiency on mod launch, you can go into the P3DChunks folder and delete any chunk type you're not using.

3) Loading LuaP3DLib

Now that Custom Files is enabled, and the LuaP3DLib files are present, the next step is to load the library in your mod. To do this, create a file called CustomFiles.lua in the same root directory as Meta.ini. This file is executed on mod launch, and is where we'll load our library.

-- Create a Paths table for common paths
Paths = {}
Paths.ModPath = GetModPath() -- GetModPath is a mod launcher function that gets the root of your mod
Paths.Resources = Paths.ModPath .. "/Resources" -- Path Handlers and other file resources will be in this folder
Paths.Lib = Paths.Resources .. "/lib" -- Any libraries, such as the LuaP3DLib, will be in here

-- Execute LuaP3DLib. This creates the `P3D` global table, and all the related functions and classes.
dofile(Paths.Lib .. "/P3D2.lua")
-- This function loads all P3D chunks from a specified folder.
P3D.LoadChunks(Paths.Lib .. "/P3DChunks")

Your mod is now configured to use the LuaP3DLib in any path handlers or other Lua code. See the next page for how to handle a file.

Configuring an external Lua environment

Sometimes, when testing or doing bulk P3D edits for example, you will want to use the library in a standalone Lua environment, without the custom mod launcher functions. To do this, you have to create the required functions yourself.

1) Getting the Lua binary

The mod launcher uses Lua 5.3.5, so that is the version the library is built for. It should be compatible with other versions, but if you want certainty your code is compatible, I recommend using this version.

You can download the compiled binaries Sourceforge, with 5.3.5 being available here.

To test your script, open a command line and run lua.exe Path/To/Script.lua. For example, lua.exe Test.lua, if your script is called Test.lua and is in the same directory as Lua.exe.

2) Creating the mod launcher functions

LuaP3DLib uses the following mod launcher functions:

We can recreate these in Lua in order to make the library function.

function Exists(Path, IsFile, IsDirectory)
	if IsDirectory then
		local lastChar = Path:sub(-1)
		if lastChar ~= "/" and lastChar ~= "\\" then
			Path = Path .. "\\"
		end
	end
	local success, err, code = os.rename(Path, Path)
	if not success then
		if code == 13 then
			return true
		end
	end
	return success, err
end

function DirectoryGetEntries(Path, Callback)
	local lastChar = Path:sub(-1)
	if lastChar ~= "/" and lastChar ~= "\\" then
		Path = Path .. "\\"
	end
	
	local pfile = io.popen('dir "' .. Path .. '" /b /ad')
	for file in pfile:lines() do
		if not Callback(file, true) then
			pfile:close()
			return
		end
	end
	pfile:close()
	
	local pfile = io.popen('dir "' .. Path .. '" /b /a-d')
	for file in pfile:lines() do
		if not Callback(file, false) then
			pfile:close()
			return
		end
	end
	pfile:close()
end

function GetFileExtension(Path)
	local ext = Path:match(".+(%..-)$")
	return ext
end

function ReadFile(path)
	local file = io.open(path, 'rb')
	local contents = file:read("a*")
	file:close()
	return contents
end

Note: Exists and DirectoryGetEntires only work on Windows.

3) Loading LuaP3DLib

The better way to load LuaP3DLib, outside of the mod launcher environment, is to use the require function. To do this, you need to configure your package.path.

For this example, I have the files extracted from P3D.zip in a folder at S:\\LuaP3DLib.

-- Set the package path to the LuaP3DLib folder
package.path = "S:\\LuaP3DLib\\?.lua"
-- Require the library
require("P3D2")
-- Load the P3D chunks
P3D.LoadChunks("S:\\LuaP3DLib\\P3DChunks")

You Lua script is now setup to use the library to read and modify Pure3D files.

Clone this wiki locally