Add Files

Updated for version 4.0.

The module inherits ModuleBase. All parameters and functions of this class are inherited by the module.

Module name

The name of the module you use as the meta of the module definition is 'AddFiles' or 'AddFilesModule' if _force_search is set to true in the module definition.

XML Structure

<AddFiles directory force_all use_clbk>
    <extension path force load reload unload/>
</AddFiles>

<AddFiles directory force use_clbk ...>

Parameter	Type	Description
directory	String	directory/path relative to the mods directory which contains all files to be added
use_clbk	String	Pointer to a function which should return a value that determines if the added files should be added. Example: "self:UseClbk"
unload_on_restart	Boolean	Determines whether to unload files when the game is restarted

<extension path force load reload unload .../>

Parameter	Type	Description
extension	String	The extension/type of the file you are adding
path	String	Path of the file you wish to add (without the extension), relative to your mod's directory and the directory you may or may not have specified in the main node.[REQUIRED]
force	Boolean	Determines if the file should be forced to be added even if a file with the extension and path is already in the database. Defaults to true and can be inherited from the parent node
force_if_not_loaded	Boolean	Sort of like force but checks if the file is not loaded in the memory
load	Boolean	Determines if the file should be loaded through dyn_resource as soon as it is available. Defaults to false. _Can be inherited from the parent node_ Scroll down to know more about load
unload	Boolean	Determines if the file should be unloaded when the AddFilesModule is unloaded. Defaults to true. Can be inherited from the parent node
reload	Boolean	Determines if the file should be called with PackageManager:reload after it has been added. Defaults to false. Can be inherited from the parent node
full_path	String	Allows you to define a full path instead of automatic path that is constructed from the directory value
auto_cp	Boolean	Determines if an automatic cooked physics should be loaded. This means a cooked physics from BeardLib there isn't a need to create a file for it. This is highly recommended when your cooked physics is 0 bytes. Some units don't require a cooked_physics file. _Can be inherited from the parent node_
use_clbk	String	Pointer to a function which should return a value that determines if the file should be added. Example: "self:UseClbk"

<add ...>

Allows you to categorize your added files. Useful when you add a few units and want to keep track of the dependencies of the unit. Used in custom levels' add.xml.

Has the same parameters as and accepts files.

Note: custom levels' add.xml use path and type parameter in their <add>. This is only used by the editor. You can categorize them with comments.

Types/Load

Any file that exists in the game can be added through AddFiles. It doesn't mean all will load but most do.

Does not need load=true:

The files either don't need load at all (like textures). Or, are loaded automatically by BeardLib when they are used

• texture/dds/png/tga

• bik/movie

• unit

• object

• material_config

• sequence_manager

• cooked_physics (Added automatically for new units)

• effect (supposed to load by itself, if it doesn't work you can still try load=true)

• environment

• mission

• continent

• world

• any scriptdata

Needs load=true:

• font

• scene

Untested

• merged_font

• strings

• bnk

Example

This example is what you would put inside your main node within your mod config

<AddFiles directory="assets">
    <texture path="guis/textures/my_texture"/>
</AddFiles>

For this example you would have your custom texture like this: mods/MyMod/assets/guis/textures/my_texture.texture

If you are using this module in a BLT mod.

Example of using <add>

<AddFiles directory="assets">
    <texture path="guis/textures/my_texture"/>
    <add>
        <movie path="path/to/movie"/>
        <unit path="path/to/unit"/>
    </add>
</AddFiles>

Shortcuts

Introduced in 3.38.

Shortcuts are mainly for units and are used to add units using special metas that "guess" your files based on a path you provide. There are also some for textures. This let's you reduce the amount of copy pasting you have to do in AddFiles.

Things to know:

• Most paths are supposed to be the same (except of course the extension). But, things like textures are path + _df and path + _nm.

• df stands for diffuse and nm stands for normal.

• cc is the texture used for skins.

• thq stands for (presumably) third-person high quality and are essentially the high quality third models. Mostly the templates already have the things in the material config setup so you don't have to touch it. That also has a cc variant (Weird I know).

• auto_cp option above is actually turned on here by default. This means you don't have to include cooked_physics. If your unit does use cooked physics (meaning the cooked physics file isn't 0kb) you should set this value to false. In some cases, the unit doesn't need a cooked physics at all so there you should turn that off too.

Current shortcuts:

Meta	Description
unit_obj	Adds unit, model, and object (object and model always have the same path)
unit_tex	Adds unit, model, object, material_config, and textures
unit_seq	Adds unit, model, object, material_config, textures, and sequence_manager
unit_mat	Adds unit, model, object, and material_config
unit_mat_seq	Adds unit, model, object, material_config and sequence_manager
unit_obj_seq	Adds unit, model, object, and sequence_manager
unit_thq	Adds unit, model, object, material_config, textures, and _thq material_config (path + _thq)
unit_mat_thq	Adds unit, model, object, material_config, and _thq material_config
unit_npc	Adds unit, model, object, and npc unit (path + _npc)
unit_cc	Adds unit, model, object, material_config, textures, _thq material_config, _cc material_config, _cc_thq material_config and _df_cc texture
unit_mat_cc	Adds unit, model, object, material_config, _thq material_config, _cc material_config, and _cc_thq material config
df_nm	Adds textures (path + _df and path + _nm)
df_nm_cc	Adds textures and cc texture (path + _df_cc)
df_nm_cc_gsma	Adds textures, cc texture, and gsma texture (path + _gsma)
df_nm_gsma	Adds textures, textures, and gsma texture

Remember that these replace the meta name. So you'll write it like

<unit_obj path="path"/>

This will add a unit, model, and an object that are all located in path (path is a file path) If we were to use unit_tex it would add material_config too and textures which would be in path + _df, path + _nm

The parameters these nodes accept are: path, full_path, file_path, and auto_cp (custom_cp only working in unit_x of course).

Possibly in the future this list may expand. It's also possible that a feature will be added to add shortcuts.

Auto Generation

Introduced in 4.0.

A step up to shortcuts; now you can forget about adding entries every time.

Warning: it's currently being tested and some things may not work as intended.

To use this in the most simple way, you just need to add auto_generate="true" to the AddFiles config.

This will auto generate an xml which by default will be named gen_add.xml. The file will be generated once and that's it.

If you want to have it generate every reload, go to the your mod's settings in the BeardLib Mods Manager and enable "Develop Mode". This will tell BeardLib that the mod is being developed and it should auto generate it every reload.

Need more options? Remove that auto_generate value and convert it to:

<auto_generate>
</auto_generate>

XML Structure:

Now for the structure and how to do some things.

<AddFiles directory="assets">
    <auto_generate ...>
        <ignore>
            <unit/> <!--Ignores type unit-->
            <unit path/> <!--Ignores path + unit -->
            <table path/> <!--Ignores path -->
            <table pattern/> <!--Ignores all files matching the pattern -->
        </ignore>
        <set>
            <unit .../> <!--Set any unit-->
            <unit path .../> <!--Set unit with path-->
            <table path .../> <!--Set any file equal to that path-->
            <table .../> <!--Set any file-->
            <table pattern .../> <!--Set any file matching the pattern-->
        </set>
    </auto_generate>
</AddFiles>

<auto_generate ...>

Uses the same parameters as <AddFiles>. It will inherit the top AddFiles's values.

Parameter	Type	Description
file	String	Path to the file that will be auto generated. Defaults to gen_add.xml (Do not confuse with add.xml. gen_add.xml is loaded by the module not framework).

<ignore>

Let's you ignore files using: paths, types and patterns.

To ignore a type, simply write:

<ignore>
    <unit/>
</ignore>

To ignore a path, write:

<ignore>
    <table path="path/to/file"/>
</ignore>

This will ignore all paths that equal to "path/to/file"

To ignore a path AND type, write:

<ignore>
    <unit path="path/to/file"/>
</ignore>

This will ignore a unit with the path "path/to/file"

Patterns

Patterns let you ignore multiple files that match the pattern you write. This utilizes lua patterns (which you can read in here about). Let's see an example:

<ignore>
    <table pattern="_barrel"/>
</ignore>

This will ignore all files that match this pattern. If you want to specify a type you'd write it like this:

<ignore>
    <unit pattern="_barrel"/>
</ignore>

Remember! This uses lua patterns so you must be aware of the magic characters. The following characters must be escaped if you want to use them normally: +, -, . and %. Escape them by placing a % before them. Generally, these shouldn't be used in file/folder names.

<set>

Uses similar syntax to ignore. So read that first.

Not everything can be automated. And so, sometimes we need to set values for some files.

Let's say you want to set load for all units:

<set>
    <unit load="true"/>
</set>

What about a specific unit?

<set>
    <unit path="path/to/unit" load="true"/>
</set>

Multiple values and setting them for all paths that equal:

<set>
    <table path="path/to/unit" unload="true" load="true"/>
</set>

And of course, patterns:

<ignore>
    <table pattern="_barrel" load="true"/>
</ignore>

Or a unit with patterns:

<ignore>
    <unit pattern="_barrel" auto_cp="true"/>
</ignore>

Functions

Function	Description
Load()	This is called normally by the module's init function, this is what adds all the files to the game that have been defined in the module definition
Unload()	This will remove all the added files from the game's database. This is only called by default if the AddFilesModule has been added through the LevelModule
LoadPackageConfig(...)	Same as in BeardLibPackageManager. Called in :Load()
UnloadPackageConfig(...)	Same as in BeardLibPackageManager. Called in :Unload()
AddFileWithCheck(...)	Same as in BeardLibPackageManager