------------------------------------------------------------------ Description ------------------------------------------------------------------ Patchinf is a wad text lump that specifies small changes (patches) on maps. The lump consists of one or more sections pertaining to a map; each section is introduced by the map name enclosed in square brackets (ie., same as in sectinfo or windows ini files). The mapname may be equal to "*" which means that the patch commands in there will apply to all maps; we'll call this a "global section". If such a section exists, as well as other "map-specific" sections, then the global section will be combined with the map-specific sections with the latter being executed after (ie., overriding) the global section. One could have multiple patchinf lumps; they're read in wad-loading order and their contents "added up"; if there is more than one section with the same map name (eg., [map01] from wad A and [map01] from wad B), then all but the last one are discarded. ------------------------------------------------------------------ Sample Syntax ------------------------------------------------------------------ // Some comment /* Multiple line comment */ [*] [map01] [map02] ------------------------------------------------------------------ Comments ------------------------------------------------------------------ Comments are introduced by two forward slash characters // and continue to the end of line. A Multi-line comment is started with /* and ended with */ Comments must occur between sections or commands; not in the middle of some command. ------------------------------------------------------------------ Patch Commands ------------------------------------------------------------------ Patch commands follow a "function-like" syntax; you don't need semi-colons or other terminators/separators. Commands can span more than one line. The command parameters can consist of 'filters' and 'new values'. Delete commands only consist of 'filter' parameters, Add commands consist of only 'new value' parameters, Change commands consist of both 'filter' and 'new value' parameters. Filter parameters are used for narrowing down which things the command will match with. Using a * for a filter parameter means that the attribute of the filter will be ignored for the matching. New values are simply new values for the attributes of the thing affected by the command. For add commands these are the values of the attributes of the new thing. For change commands these are the values that the attributes of affected things will be changed to. Using a * for a new value parameter in change commands means that the given attribute should be kept as is. 1. Thing_Delete (type [, flags [, x [, y [, z] ] ] ] ) Deletes things with a given type (ie., of a given edit_id). If you specify flags (in doom format) or x/y/z you can narrow down the thing matching. If for example you specify only the type, then all things having that type will be deleted. If you specify type and flags, then only things with the given type and flags will be deleted. If you specify type, flags, x and y, then you need a match on all 4 for the thing to get deleted. And if you specify all 5 parameters, then you need a match on all 5 for the thing to be deleted. If you need to specify a later value (z for example) and you don't want to specify previous values (x, y for example), you can use * for the unspecified values. NOTE: if this command is used in the global section, it should NOT specify x/y/z. It will get rejected if it does. 2. Thing_ById_Delete (id) Deletes a specific thing in the map, this is specified by the given unique id number. NOTE: this command cannot be used in the global section: it will get rejected. 3. Thing_Change (type, flags, x, y, z, new_angle, new_type, new_flags) Changes things matched by the first five 'filter' parameters. You can use * to ignore some of the filters. The last 3 parameters are the new values for the angle, type (edit_id) and flags (doom format) attributes of the matched things. To keep an attribute as-is, you can use a * for the 'new value'. NOTE: if this command is used in the global section, it should NOT specify x/y/z. It will get rejected if it does. 4. Thing_ById_Change (id, new_angle, new_type, new_flags) Changes a specific thing in the map, which is specified by its unique id number. The last 3 parameters specify the new angle, type (edit_id) and flags (doom format) that will be set. To keep the old value, you can use * for any of the new values. NOTE: this command cannot be used in the global section: it will get rejected. 5. Thing_Add (type, x, y, angle, flags) Adds a thing of the given type (edit_id) at position x/y and with the given angle and flags (doom format options). NOTE: this command cannot be used in the global section: it will get rejected. 6. Thing_AddZ (type, x, y, z, angle, flags) Adds a thing of the given type (edit_id) at position x/y/z and with the given angle and flags (doom format options). NOTE: this command cannot be used in the global section: it will get rejected. - Hexen format commands - 7. ThingH_Change (type, flags, tag, special, x, y, z, new_angle, new_type, new_flags, new_tag, new_special, new_arg1, ..., new_arg5) Changes things matched by the first seven 'filter' parameters. You can use * to ignore some of the filters. The rest of the parameters are the new values for the attributes of the matched things. To keep an attribute as-is, you can use a * for the 'new value'. The flags are in hexen format. The parameters after new_flags are optional, if left out, the old values will be kept for them. NOTE: if this command is used in the global section, it should NOT specify x/y/z. It will get rejected if it does. 8. ThingH_ById_Change (id, new_angle, new_type, new_flags, new_tag, new_special, new_arg1, ... , new_arg5) Changes a specific thing in the map, which is specified by its unique id number. The new flags are in hexen format. You can use * to keep the old value instead of specifying a new value. The parameters after new_flags are optional, if left out, the old values will be kept for them. NOTE: this command cannot be used in the global section: it will get rejected. 9. ThingH_Add (type, x, y, z, angle, flags, tag, special, arg1, arg2, arg3, arg4, arg5) Adds a thing of the given type (edit_id) at position x/y/z and with the given angle, flags (hexen format), tag, special, and arguments. The parameters after flags are optional, if left out, 0 will be used for them. NOTE: this command cannot be used in the global section: it will get rejected. ------------------------------------------------------------------ Implementation: how patchinf is applied during map load and how global/local are combined. ------------------------------------------------------------------ The general idea is to apply a "pass/reject/modify" rule to each thing spawned at map load. For each item that is about to be spawned on the map, we employ the following rules in the given order: 1. Apply the replace and delete *local* rules in the order specified in the local patchinfo lump. Once a matching rule is found, the processing of the local patchinfo stops. 2. If the item has been deleted by local patchinfo, then nothing more needs to be done. 3. If the item has been left alone or replaced by local patchinfo, then we go to the global patchinfo. There we apply the replace and delete *global* rules (on the item as has been modified by the local rules). Once a matching rule is found, the processing of the global patchinfo stops. The above rules apply for delete/replace rules only. After all things on the map have spawned (and before any scripts start executing), we go to the local patchinfo lump and apply the "add" rules. ------------------------------------------------------------------