Difference between revisions of "Modular Tables"

From FreeSpace Wiki
Jump to: navigation, search
m
(modular messages)
 
(52 intermediate revisions by 13 users not shown)
Line 1: Line 1:
Modular tables are SCP addition to the standard FreeSpace table system. XMTs (or eXtentable Modular Tables) offer capability to add new entries or alter already existing tables without any need of editing the 'parent' table file.
+
'''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.
  
==Extentable Tables==
+
The base table each modular table modifies depends on the ending three letters of its name. See [[Modular Tables#Supported Modular Tables|the list of supported modular tables]] below.
*[[armor.tbl]] can be extended with '''xxx-amr.tbm file''' (non-XMT)
 
*[[hud_gauges.tbl]] can be extended with '''xxx-hdg.tbm file''' (non-XMT)
 
*[[music.tbl]] can be extended with '''xxx-mus.tbm file''' (non-XMT)
 
*[[Ships.tbl]] can be extented with '''xxx-shp.tbm file''' (XMT)
 
*[[Weapons.tbl]] can be extended with '''xxx-wep.tbm file''' (XMT)
 
*[[Weapon_expl.tbl]] can be extended with '''xxx-wxp.tbm file''' (non-XMT)
 
  
==Important Notes==
+
 
*Modular table files should use the 'parent table' files sections.
+
[[Tables|List of Tables]]
*Completely new entries and also complete rewrites of entries in parent table file are always possible.
+
 
*For '''xxx-shp.tbm''' and '''xxx-wep.tbm'''
+
==Important Notes==
**Table entries in modular tables do not have to be complete. Partial entries can be used to alter the data found in parent table files when only some changes to the original are desired to be made.
+
===Loading Order===
**Adding '''+nocreate''' right after the entry's name 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.
+
* Modular table files should use the 'parent table' sections. They should also keep their entry order.
***Example:
+
* 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 [[Command-Line_Reference#-mod|-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.<br><br><font color=red>'''EXTREMELY IMPORTANT NOTE:'''</font> 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.<br><br>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.<br><br>
 +
** 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
 
   $Name:              @Subach HL-7
 
       +nocreate
 
       +nocreate
 +
 +
==Supported Modular Tables==
 +
The list of supported tbms is:
 +
 +
*[[ai.tbl]] can be extended with '''xxx-aic.tbm''' (XMT)
 +
*[[ai_profiles.tbl]] can be extended with '''xxx-aip.tbm''' (XMT)
 +
*[[armor.tbl]] can be extended with '''xxx-amr.tbm''' (non-XMT)
 +
*[[asteroid.tbl]] can be extended with '''xxx-ast.tbm''' (XMT)
 +
*[[autopilot.tbl]] can be extended with '''xxx-aplt.tbm''' (non-XMT)
 +
*[[cheats.tbl]] can be extended with '''xxx-cht.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)
 +
*[[cutscenes.tbl]] can be extended with '''xxx-csn.tbm''' (XMT)
 +
*[[fireball.tbl]] can be extended with '''xxx-fbl.tbm''' (non-XMT)
 +
*[[fonts.tbl]] can be extended with '''xxx-fnt.tbm''' (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)
 +
*[[iff_defs.tbl]] can be extended with '''xxx-iff.tbm''' (XMT)
 +
*[[lightning.tbl]] can be extended with '''xxx-ltng.tbm''' (XMT)
 +
*[[mainhall.tbl]] can be extended with '''xxx-hall.tbm''' (non-XMT)
 +
*[[medals.tbl]] can be extended with '''xxx-mdl.tbm''' (XMT)
 +
*[[messages.tbl]] can be extended with '''xxx-msg.tbm''' (non-XMT)
 +
*[[mflash.tbl]] can be extended with '''xxx-mfl.tbm''' (non-XMT)
 +
*[[music.tbl]] can be extended with '''xxx-mus.tbm''' (XMT)
 +
*[[nebula.tbl]] can be extended with '''xxx-neb.tbm''' (XMT)
 +
*[[objecttypes.tbl]] can be extended with '''xxx-obt.tbm''' (XMT)
 +
*[[rank.tbl]] can be extended with '''xxx-rnk''' (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)
 +
*[[species.tbl]] can be extended with '''xxx-intl.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)
 +
*[[tips.tbl]] can be extended with '''xxx-tip.tbm''' (XMT)
 +
*[[traitor.tbl]] can be extended with '''xxx-trtr.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==
 
==Sample - Alpha-wep.tbm==

Latest revision as of 16:15, 17 April 2023

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.tbl can be extended with xxx-aic.tbm (XMT)
  • ai_profiles.tbl can be extended with xxx-aip.tbm (XMT)
  • armor.tbl can be extended with xxx-amr.tbm (non-XMT)
  • asteroid.tbl can be extended with xxx-ast.tbm (XMT)
  • autopilot.tbl can be extended with xxx-aplt.tbm (non-XMT)
  • cheats.tbl can be extended with xxx-cht.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)
  • cutscenes.tbl can be extended with xxx-csn.tbm (XMT)
  • fireball.tbl can be extended with xxx-fbl.tbm (non-XMT)
  • fonts.tbl can be extended with xxx-fnt.tbm (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)
  • iff_defs.tbl can be extended with xxx-iff.tbm (XMT)
  • lightning.tbl can be extended with xxx-ltng.tbm (XMT)
  • mainhall.tbl can be extended with xxx-hall.tbm (non-XMT)
  • medals.tbl can be extended with xxx-mdl.tbm (XMT)
  • messages.tbl can be extended with xxx-msg.tbm (non-XMT)
  • mflash.tbl can be extended with xxx-mfl.tbm (non-XMT)
  • music.tbl can be extended with xxx-mus.tbm (XMT)
  • nebula.tbl can be extended with xxx-neb.tbm (XMT)
  • objecttypes.tbl can be extended with xxx-obt.tbm (XMT)
  • rank.tbl can be extended with xxx-rnk (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)
  • species.tbl can be extended with xxx-intl.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)
  • tips.tbl can be extended with xxx-tip.tbm (XMT)
  • traitor.tbl can be extended with xxx-trtr.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