TFE Custom Logics

This article explains how to use custom (user-defined) AI logics in TFE. (The feature is not yet available but will be coming in a future official release.)

This feature allows modders to create new enemy logics that behave similarly to the "standard" (non-boss) enemies in Dark Forces, for example Officers, Stormtroopers, Bossk, Probe Droids.

To use the feature, check that the Enable custom AI logics from JSON files setting has been enabled, in Settings → Game Settings → Dark Forces Settings.

JSON locations

Custom logics are defined in JSON files. TFE will search for and load logics from all logic .JSON files found in these locations

• DARK\Logics
• TheForceEngine\Mods\Logics
• TheForceEngine\Mods\[CURRENTLY LOADED MOD]\Logics

where DARK is your Dark Forces game directory which TFE is pointing to.

In addition, if you are running a Mod from a ZIP, TFE will look for a \Logics subfolder inside the ZIP and load logics from any .JSON files found there.

Logics loaded from a Mod will take preference over any logics found in other locations that have the same name.

You can have as many logic .JSON files as you want, and each .JSON file can contain as many logics as you want. If multiple logics are loaded that have the same name, only the first one encountered with that name will be used. If you have multiple .JSON files, the order in which they are loaded by TFE is unpredictable, so the only way to be sure that your logics work the way you intend is to avoid duplicate names.

Note: Custom logics are loaded when entering Dark Forces from TFE, and cleared when the user exits back to the TFE main menu. Therefore, if JSON files are altered while the game is running, the change will take effect when you quit back to the TFE main menu and then re-enter the game.

Logic JSON structure

A logic JSON should consist of a single array called "logics".

Each element of the "logics" array must consist of two items, in this order

• "logicName" - a string which is the name of the logic
• "data" - an object containing properties that are set for the logic

Example:

{
   "logics": [
      {
         "logicName": "LogicA",
         "data": {
            "alertSound": "alert1.voc",
            "painSound": "pain1.voc",
            "hitpoints": 25,
            "projectile": "rifle_bolt"
         }
      },
      {
         "logicName": "LogicB",
         "data": {
            "alertSound": "alert2.voc",
            "painSound": "pain2.voc",
            "hitpoints": 39,
            "speed": 20,
            "projectile": "thermal_det",
            "dropItem": "red_key"
         }
      }
   ]
}

Logic JSONs are not case sensitive. The text inside the JSON can be all uppercase, all lowercase, or any mix of upper and lowercase; it will all be read the same.

For example, "alertsound", "ALERTSOUND", "AlertSound", "alertSound" will all be accepted.

Further tips about getting the JSON format right can be found on the TFE MOD Overrides article.

Data properties

Here is a list of the properties that you can set for each logic. They are all standard JSON key-value pairs.

You do not need to set every property. Unset properties will default to the values shown.

Properties can be listed in any order. Property names are not case sensitive, but need to be spelled correctly.

Property	Type	Default value	Description
hasGravity	boolean	true	If true, will be affected by gravity
isFlying	boolean	false	If true, will be a flying enemy (like probe droid)
fieldOfView	number (integer)	210	Field of view, in degrees. If set to 360, the enemy will be able to see you even if you are standing behind it.
awareRange	number (integer)	20	If you are within this distance from the enemy (in DFU), it will be alerted even if you are outside its field of view. (However, this can be affected by other things, such as the ambient light.)
alertSound	string	no sound	VOC file to play when enemy is alerted
painSound	string	no sound	VOC file to play when enemy takes pain
dieSound	string	no sound	VOC file to play when enemy dies
attack1Sound	string	no sound	VOC file to play for primary attack
attack2Sound	string	no sound	VOC file to play for secondary attack
hitPoints	number (integer)	4	Hitpoints. The enemy will die when it reaches 0.
dropItem	string or number	-1 (nothing)	What item is dropped when the enemy dies. See reference table below for options.
dieEffect	string or number	-1 (nothing)	An effect (eg. explosion) that will play when the enemy dies. See reference table below for options.
hasMeleeAttack	boolean	false	If true, the enemy will have a melee attack. If the enemy has a melee attack, it will always be the primary attack.
hasRangedAttack	boolean	true	If true, the enemy will have a ranged attack. If the enemy has a melee attack, the ranged attack will be the secondary attack. If it does not have a melee attack, the ranged attack will be the primary attack.
litWithMeleeAttack	boolean	false	If true, the sprite will light up when it attacks with melee.
litWithRangedAttack	boolean	true	If true, the sprite will light up when it does its ranged attack.
projectile	string or number	"rifle_bolt"	What projectile the enemy will fire for its ranged attack. See reference table below for options.
wanderTime	number (integer)	300	How long (in seconds) the enemy will keep looking for the player, before it returns to its idle or "asleep" state. This time is reset when the enemy is re-alerted by the player.
rangedAttackDelay	number (decimal)	2	Time delay in seconds between range attacks (the game engine adds some variability to this)
meleeAttackDelay	number (decimal)	0	Time delay in seconds between melee attacks
meleeRange	number (integer)	0	Range (in DFU) of melee attack - how far the player can be from the enemy to be hit by it.
meleeDamage	number (integer)	0	Damage that each melee attack will inflict.
minAttackDist	number (integer)	0	Minimum distance from the player (DFU) where the enemy will attack with its ranged weapon.
maxAttackDist	number (integer)	160	Maximum distance from the player (DFU) where the enemy will attack with its ranged weapon.
fireSpread	number (integer)	30	Accuracy of fire. Lower numbers are more accurate.
speed	number (integer)	4	Speed of enemy's movement, appears to be in DFU per second. For flying enemies, this is their horizontal speed.
verticalSpeed	number (integer)	10	For flying enemies only, this is their vertical speed.
rotationSpeed	number (integer)	720	Speed at which the enemy can rotate. Degrees per second.

Using custom logics

Logics that you have defined in JSON can be applied to a sprite in the .O file in the same way as other (hardcoded) enemy logics. For example, if you have the following logic

      "logicName": "Rodian",
      "data": {
         "alertSound": "rodian1.voc",
         ....
      }

Apply it to a sprite (WAX) like this, and then the sprite should behave with the custom logic.

SEQ
   LOGIC: Rodian
SEQEND

You can also use JSON-defined logics with generators, for example

SEQ
   LOGIC:         GENERATOR Rodian
   DELAY:         10
   INTERVAL:      5
   NUM_TERMINATE: 6
   MAX_ALIVE:     1
   MAX_DIST:      800
   MIN_DIST:      50
SEQEND

Important: If a level with a custom logic is run with vanilla Dark Forces or the Dark Forces Remaster, the sprites will be "lifeless". However, if the level has generators with a custom logic, this causes the original game to crash.

Overriding hardcoded logics

You can override hardcoded logics by creating a JSON logic with the same name as one of the hardcoded logics. For example, storm1 and commando.

If you override a boss logic, like kell or one of the dark troopers, the enemy will behave like an ordinary enemy instead of a boss; they will lose their ability to trigger the BOSS elevator when they die.

Custom logics and WAX files

A custom logic's behaviours/actions will correspond to WAX animations as follows

0	Walking / moving
1	Primary attack
2	Melee death
3	Shooting / explosion death
4	Dead
5	Idle / stationary
6	Primary attack conclusion (eg. recoil)
7	Secondary attack
8	Secondary attack conclusion
9	unused
10	unused
11	unused
12	Pain

This follows the same pattern as all the standard Dark Forces enemies.

Note that if a logic has a melee attack, this will always be the primary attack (animations 1 and 6). If a logic has only a ranged attack, then this will be the primary attack (animations 1 and 6). If a logic has both melee and ranged attacks, the melee will be primary (animations 1 and 6) and the ranged attack will be secondary (animations 7 and 8).

Reference

Projectile list

You can assign projectiles with either their number or their string. Make sure strings are spelled correctly, exactly as shown in this table (either lowercase or uppercase may be used).

Number	String
-1		Enemy will not have a projectile
0	punch	This is a special projectile used for the player's fists, and may not work with logics
1	pistol_bolt
2	rifle_bolt
3	thermal_det
4	repeater
5	plasma	Fusion cutter projectile
6	mortar
7	land_mine
8	land_mine_prox	Proximity land mine
9	land_mine_placed
10	concussion
11	cannon
12	missile
13	turret_bolt
14	remote_bolt
15	exp_barrel	An invisible projectile that is normally spawned when a barrel explodes
16	homing_missile	Mohc's homing missiles
17	probe_proj	Green interrogator droid projectile
18	bobafett_ball	Boba Fett's missiles

Drop item list

You can assign drop items with either their number or their string. Make sure strings are spelled correctly, exactly as shown in this table (either lowercase or uppercase may be used).

Number	String
-1		Enemy will not drop anything when they die
0	PLANS	Death Star plans
1	PHRIK
2	NAVA
3	DT_WEAPON
4	DATATAPE
5	RIFLE
6	AUTOGUN
7	MORTAR
8	FUSION
9	CONCUSSION
10	CANNON
11	ENERGY
12	POWER
13	PLASMA
14	DETONATOR
15	DETONATORS
16	SHELL	Mortar shell
17	SHELLS
18	MINE
19	MINES
20	MISSILE
21	MISSILES
22	SHIELD
23	RED_KEY
24	YELLOW_KEY
25	BLUE_KEY
26	GOGGLES
27	CLEATS
28	MASK	Gas mask
29	BATTERY
30	CODE1
31	CODE2
32	CODE3
33	CODE4
34	CODE5
35	CODE6
36	CODE7
37	CODE8
38	CODE9
39	INVINCIBLE	Shield supercharge
40	SUPERCHARGE	Weapon supercharge
41	REVIVE
42	LIFE
43	MEDKIT
44	PILE	Kyle's pile of weapons

Death effect list

You can assign death effects with either their number or their string. Make sure strings are spelled correctly, exactly as shown in this table (either lowercase or uppercase may be used).

Note that some effects inflict damage.

Number	String
-1		Enemy will not have a death effect
0	SMALL_EXP	small "puff" - blaster weapons
1	THERMDET_EXP	thermal detonator explosion
2	PLASMA_EXP	Green plasma "puff"
3	MORTAR_EXP	mortar explosion
4	CONCUSSION	concussion - first stage
5	CONCUSSION2	concussion - second stage
6	MISSILE_EXP	missile explosion
7	MISSILE_WEAK	weaker version of the missle explosion
8	PUNCH	punch
9	CANNON_EXP	Blue cannon "puff"
10	REPEATER_EXP	repeater "puff"
11	LARGE_EXP	Land mine explosion
12	EXP_BARREL	exploding barrel
13	EXP_INVIS	an explosion that makes no sound and has no visual effect
14	SPLASH	water splash
15	EXP_35	medium explosion, 35 damage (used for probe droid death)
16	EXP_NO_DMG	medium explosion, no damage (used for turret and welder deaths)
17	EXP_25	medium explosion, 25 damage (used for Boba Fett missile explosions)