Tutorial; Relative File Paths - HWRM/KarosGraveyard GitHub Wiki

The Problem

When calling a function such as dofilepath/doscanpath, the function needs to know the exact location of the file.

This is usually allowed to be an "absolute file path", which begins at the system's root. Absolute paths might look like:

C:\Program Files (x86)\Steam\steamapps\common\Homeworld\HomeworldRM\Data\my-file.lua

~/Documents/MyProject/my-file.txt

However, the root directory to begin looking from is not guaranteed to be the same in all contexts. For example, Homeworld will actually begin most directory searches from the C:\Program Files (x86)\Steam\steamapps\common\Homeworld\ directory rather than C: (but not always).

The Solution

Because of how much overhead could go into managing file path roots, most tools have some form of support for relative paths. Relative paths might look like this (in Homeworld):

data:my-file.lua

data:scripts/hiigaran/some-file.lua

player:PLAYERCFG.lua

These paths begin with a prefix, which is always in the form <location>: (with a colon). These locations are aliases for absolute paths, and are also guaranteed to work the same way regardless of where in the filesystem your code is running.

💡 When used by modded files, the data: alias (and any subdirectory aliases such as locale:) refers to the root directory of your mod. This makes data: extremely useful when using dofilepath/doscanpath to load other files from the stock library of files or from your own custom modded files.

The following is a table of availble path aliases (the root directory is always the Homeworld directory).

Prefix	Location	Description
`data:`	`HomeworldRM\Data`	The `data` path is the location of most assets & game files not included in the binary. This alias will instead correspond to the root directory of the mod when used while writing modded files. This is because mod files are overwritten on top of the base data found in the `.big` resource files.
`bin:`	`HomeworldRM\Bin`	This directory contains a bunch, including the actual game binary, player profiles, and a screenshots directory. The `Release` directory is particularly useful as it houses the `HwRM.log` file used by `print` calls, as well as `autoexec.lua`.
`profiles:`	`HomeworldRM\Bin\Profiles`	Containing all player profile data folders `Profile<n>`, which include save data and stats.
`player:`	`HomeworldRM\Bin\Profiles\Player<n>`	Corresponds to the profile directory for the currently loaded profile (from the main menu).
`locale:`	`HomeworldRM\Data\Locale`	Localisation data which is used for movies & most of the text ingame. Since this is a subdirectory of the `data` directory, this means you can write your own locale dictionaries. Extract any of the `<language>.big` archives to see examples.
`builtin:`	unknown	unknown
`gamerules:`	Presumably `HomeworldRM\Data\scripts\rules`	Files containing the rule functions & configs for various game modes.
`speech:`	`HomeworldRM\Data\Sound\Speech`	Contains subdirectories for the various speech files by context, typically in `.wav` format. Also used by `Sound_SpeechSubtitlePath`.

⚠️ This list may be incomplete!

Examples

We can use the aliases to ensure we're loading the correct file, with no worry about root directories:

my-cool-mod/
| - scripts/
  | - my-custom-file.lua
| some-other-file.lua

We want to load my-custom-file into our some-other-file script, we can do that with dofilepath:

dofilepath("data:scripts/my-custom-file.lua"); -- from \Data\scripts\my-custom-file.lua

Since Homeworld works by temporarily overlaying mod files over the top of the stock files (in the \Data directory), this means the data: alias refers to the root directory of your mod!