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 ...>

ParameterTypeDescription

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 .../>

ParameterTypeDescription

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:

MetaDescription

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.

ParameterTypeDescription

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

FunctionDescription

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(...)

Last updated