Modular Tables

From FreeSpace Wiki
Revision as of 11:02, 28 August 2019 by Nightmare (talk | contribs) (Add Particle Effects)
Jump to: navigation, search

Modular tables are an SCP addition to the standard FreeSpace table system. Each modular table (.tbm extension) adds or modifies data from its related base table (.tbl extension). So there's no more need to edit the 'parent' table. A modular table file is not restricted to one entry.

The base table each modular table modifies depends on the ending three letters of its name. See the list of supported modular tables below.


List of Tables

Important Notes

Loading Order

  • Modular table files should use the 'parent table' sections. They should also keep their entry order.
  • Completely new entries and also complete rewrites of entries in parent table file are always possible.
  • Loading order:
    • The base table (.tbl) is loaded first despite its location priority, (see -mod flag help for more info about priority places). Of course, if there are several versions of the same base table in several vps or /data/tables folders, only the highest priority one will be loaded.
    • Then, ALL its related tbms are loaded, even if they are in a lower priority place than the base tbl table. I.e, tbms are always applied. If there are several versions of the same file you can imagine what happens.
    • When they are loaded, tbms start being applied in reverse priority order; ie, tbms are applied from the lowest priority place to the highest priority place.
    • The former rule makes that, if there are conflictive entries in several tables, the highest priority ones will override the rest because they will be the last applied changes.

      EXTREMELY IMPORTANT NOTE: Because of an already solved bug, fs_open versions till 3.6.9. (included) apply tbms in direct priority order, from the highest priority to the lowest one. In this way, the lowest priority entries override the rest. As example, this issue makes impossible overriding mediavps tbm settings from any tbm inside a main mod which uses this art enhancement as a secondary mod. The only way you have is overriding the whole table as explained below.

      It is not recommended to have multiple tbms inside the same priority location (vp or /data/tables folder) that contain conflicting entries. While it is possible to do so anyway, and the order is deterministic (files are loaded in reverse-alphabetical order), this is a pretty strange mod design: why should you put conflicting versions of any class of modular table in the same location? Just edit and merge them, deleting undesired entries.

    • Derived from priority and tbm handling, the only two ways to override the settings of AnExistingTable-xxx.tbm are:
      • Adding another AnExistingTable-xxx.tbm in a higher priority place so it gets loaded instead of the original version.
      • Overriding every single AnExistingTable-xxx.tbm entry, using one or several other -xxx.tbm tables located in higher priority places.

Numerical Limit

Before r11156, there was a hardcoded limit for the number of tbms of a given type that Freespace Open would recognize; the first 32 files detected by a call to parse_modular_table() were the only ones loaded. This manifested as data simply not being read by the game, and could result in the loss of, for example, ships or weapons when new ones were added. This occurred in reverse alphabetical order. In order to get around this, one had to consolidate their tbms into fewer files; now, FSO should recognize any number of files, and this should no longer be necessary.

eXtendable Modular Tables

In addition, some modular tables are XMTs (or eXtentable Modular Tables). They offer capability to add new partial entries or make partial editing to each entry. Within XMT tbms:

  • All fields are optional. But toplevel entries, of course, because you do need to specify which item you want to modify.
  • Toplevel entries can replace part of other existing toplevel entries. Only changed parameters should be specified.
  • Addition of the +nocreate parameter. This parameter should be entered right after entry name and prevents possible creation of partially undefined entry. For example, if the parent table file lacked the entry that was included to the as a partial entry to the modular table file then the creation of partially undefined entry is possible which could cause problems with the game.
    • Example:
  $Name:              @Subach HL-7
     +nocreate

Supported Modular Tables

The list of supported tbms is:

  • ai_profiles.tbl can be extended with xxx-aip.tbm (XMT)
  • armor.tbl can be extended with xxx-amr.tbm (non-XMT)
  • colors.tbl can be extended with xxx-clr.tbm (non-XMT)
  • credits.tbl can be extended with xxx-crd.tbm (non-XMT)
  • fireball.tbl can be extended with xxx-fbl.tbm (non-XMT)
  • game_settings.tbl can be extended with xxx-mod.tbm (non-XMT)
  • glowpoints.tbl can be extended with xxx-gpo.tbm (non-XMT... sort of; has +nocreate but the whole entry must be re-specified, and duplicates are discarded without +nocreate)
  • help.tbl can be extended with xxx-hlp.tbm (non-XMT)
  • hud_gauges.tbl can be extended with xxx-hdg.tbm (non-XMT)
  • mainhall.tbl can be extended with xxx-hall.tbm (non-XMT)
  • mflash.tbl can be extended with xxx-mfl.tbm (non-XMT)
  • music.tbl can be extended with xxx-mus.tbm (XMT)
  • objecttypes.tbl can be extended with xxx-obt.tbm (XMT)
  • scripting.tbl can be extended with xxx-sct.tbm (non-XMT)
  • ships.tbl can be extended with xxx-shp.tbm (XMT)
  • sounds.tbl can be extended with xxx-snd.tbm (XMT, but +nocreate is required to modify an existing entry)
  • species_defs.tbl can be extended with xxx-sdf.tbm (XMT)
  • ssm.tbl can be extended with xxx-ssm.tbm (non-XMT)
  • stars.tbl can be extended with xxx-str.tbm (non-XMT)
  • strings.tbl can be extended with xxx-lcl.tbm (non-XMT)
  • tstrings.tbl can be extended with xxx-tlc.tbm (non-XMT)
  • weapons.tbl can be extended with xxx-wep.tbm (XMT)
  • weapon_expl.tbl can be extended with xxx-wxp.tbm (non-XMT)
  • Particle Effects can be added with xxx-part.tbm (XMT; special type as it has no parent table)

Sample - Alpha-wep.tbm

  • Changes the speed of the Subach HL-7 and also adds a faint grey trail to it.
  • To create it make a text file using a text editor and save the file as Alpha-wep.tbm with the following contents to the proper folder (.../data/tables).
  #Primary Weapons
  $Name:              @Subach HL-7
     +nocreate
  $Velocity:         650.0	
  $Trail:
     +Start Width:      0.4
     +End Width:        0.0
     +Start Alpha:      0.35
     +End Alpha:        0.0
     +Max Life:         0.2
     +Bitmap:           Contrail
  #End