Difference between revisions of "Modular Tables"

From FreeSpace Wiki
Jump to: navigation, search
(Added help.tbl as a modular table.)
(modular messages)
 
(21 intermediate revisions by 4 users not shown)
Line 14: Line 14:
 
** 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.
 
** 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.
 
** 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>'''WARNING: Never use conflictive tbms inside the same priority location''', (vp or /data/tables folder). For example, do not put aaa-shp.tbm and bbb-shp.tbm inside the same vp if they have conflictive entries. Due technical design there is no easy way to know their loading order. For the final user, finally applied entries will seem randomly selected. Alphabetical sorting is not applied here. Only vps are alphabetically ordered when loaded; individual files, (like tbms), aren't, it doesn't matter if they are obtained either from hard disk folders or from inside a vp archive.<br>Nevertheless, this is a pretty strange mod design: why should you put conflictive versions of any class of modular table in the same location?, just edit and merge them deleting undesired entries. But this warning can be also understood in the following way:<Br>Be careful '''if you split one tbm in several ones''' due to any reason, (tracking changes, management of different groups of parameters or whatever), '''always check that they all are fully complementary with no conflictive entries'''.<br><br>
+
** 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:
 
** 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.
 
*** Adding another AnExistingTable-xxx.tbm in a higher priority place so it gets loaded instead of the original version.
Line 20: Line 20:
  
 
===Numerical Limit===
 
===Numerical Limit===
Although not hardcoded, there does appear to be a practical limit for the number of tbms that Freespace Open will recognize. This manifests as data simply not being read by the game, and can result in the loss of, for example, ships or weapons when new ones are added. This occurs in reverse alphabetical order. If you experience this, try consolidating your tbms into fewer files.
+
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==
 
==eXtendable Modular Tables==
Line 35: Line 35:
 
The list of supported tbms is:
 
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)
 
*[[ai_profiles.tbl]] can be extended with '''xxx-aip.tbm''' (XMT)
 
*[[armor.tbl]] can be extended with '''xxx-amr.tbm''' (non-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)
 
*[[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)
 
*[[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)
 
*[[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)
 
*[[help.tbl]] can be extended with '''xxx-hlp.tbm''' (non-XMT)
 
*[[hud_gauges.tbl]] can be extended with '''xxx-hdg.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)
 
*[[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)
 
*[[mflash.tbl]] can be extended with '''xxx-mfl.tbm''' (non-XMT)
 
*[[music.tbl]] can be extended with '''xxx-mus.tbm''' (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)
 
*[[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)
 
*[[scripting.tbl]] can be extended with '''xxx-sct.tbm''' (non-XMT)
 
*[[ships.tbl]] can be extended with '''xxx-shp.tbm''' (XMT)
 
*[[ships.tbl]] can be extended with '''xxx-shp.tbm''' (XMT)
*[[sounds.tbl]] can be extended with '''xxx-snd.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_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)
 
*[[stars.tbl]] can be extended with '''xxx-str.tbm''' (non-XMT)
 
*[[strings.tbl]] can be extended with '''xxx-lcl.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)
 
*[[weapons.tbl]] can be extended with '''xxx-wep.tbm''' (XMT)
 
*[[weapon_expl.tbl]] can be extended with '''xxx-wxp.tbm''' (non-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