[Documentation] Spawning Units from Items

[ohartenstein23]

As of the 21 August 2018 release of OXCE+, new code has been introduced that allows for the spawning of new units during the battlescape using items.  The ruleset for this feature consists of two new parameters on items:

Code: [Select]

items:
  - type: STR_SOME_UNIT_SPAWNING_ITEM
    spawnUnit: STR_SOME_UNIT # Default empty meaning don't spawn a unit, when a valid unit (defined in the units: ruleset) is defined here it will be spawned by this item.
    spawnUnitFaction: -1 # Default -1 meaning the spawned unit will be the same faction as the unit using/firing the item, this defines which faction gets the new unit:
                         #   -1: Same faction as item user
                         #    0: Player faction
                         #    1: Enemy faction
                         #    2: Civilian faction

When this item is fired/used and hits something and either causes a hit animation or an explosion, the chosen unit will be spawned after the hit/explosion.  This means that the new unit cannot be damaged by this item except during an autoshot or if terrain explosions occur after the hit.  If the tile at the center of the hit/explosion is occupied by a unit or an object, the surrounding tiles will be checked in the 3x3 'circle' around the hit/explosion, starting with the tile closest to the unit firing.  The new unit's facing will be in the same direction of the original user.  If there is no unit firing or using the item, then the search for a vaild spawn position will start on the north center tile of the surrounding 'circle' and the chosen facing for the new unit will be random.

Items that may be used to enable this behavior are:

• Firearms that use themselves as ammo - lasers, single-shot launchers, etc.
• Any ammunition for a firearm.
• Melee weapons or melee attacks on any item.
• Grenades and proximity mines.
• Psi-amps.

Player units spawned by this code will not count for the purposes of determining whether the player has any soldiers left, so you will automatically lose a mission if you lose all other units but the ones spawned this way.  Spawned player units will be automatically removed before item/unit recovery.  Enemy units spawned by this code will count for the total number of aliens left, and must be killed in order to end a mission by eliminating all hostiles.

This unit spawning also has a special interaction with items placed as part of map blocks:  any items placed on a map block as a primed grenade with a timer of 0 will spawn their unit before the battle begins but without an explosion.  The ruleset for this would look like:

Code: [Select]

items:
  - type: STR_SOME_UNIT_SPAWNING_ITEM
    spawnUnit: STR_SOME_UNIT
    spawnUnitFaction: 0
    battleType: 4 # Must be a grenade in order to spawn correctly before battle

terrains:
  - name: STR_TERRAIN_WITH_BLOCK_THAT_SPAWNS_UNITS
    mapBlocks:
      - name: MAPTOSPAWNUNITS
        items:
          STR_SOME_UNIT_SPAWNING_ITEM:
            - [0, 0, 0] # Position of the item in the map block
        fuseTimers:
          STR_SOME_UNIT_SPAWNING_ITEM: [0, 0] # Set all fuses on these items to 0
Since there is no "user" for this grenade item, the default spawnUnitFaction: -1 will cause the spawned unit to be an enemy - it is best to explicitly define this value for pre-battle unit spawning items.

[ohartenstein23]

Reserved for sample mods.

[robin]

this is amazing. thanks.

[Ethereal]

Long live the returned ability of the CELATID to clone!

[BTAxis]

So now we can have map30 in X-Com.

[Tekamthi]

sounds awesome.. think there are a few sprites floating around on these forums that have been waiting for this feature.

one thing that is unclear to me... can this be used to reliably auto spawn enemies on some modder-determined turn n, mid-mission?  My thought here would be to have the alien reproduction map items in some UFOs/bases spawn an alien maybe after ~20 turns, or even better if it could be a range like 15 to 25.. is there some way to achieve this here, or maybe cobbled through other features?

would be a great way to add a vanilla-esque sense of urgency to some missions, or secondary objectives etc.

[Yankes]

One question for code, why you did:

Code: [Select]

if (ammo->getClipSize() > 0 && item->getClipSize() > 0)In `BattlescapeGenerator::addXCOMVehicle` there is only

Code: [Select]

ammoItem->setAmmoQuantity(v->getAmmo());Should both behave same?

[ohartenstein23]

The first snippet is from the validation for loading vehicles onto the craft from the basescape; since the unit doesn't exist as a vehicle loaded on the craft before spawning it, I can't just check a 'vehicle' data structure for the ammo.

[Yankes]

Right, I miss that it get value from vehicle not item.

[SuperCaffeineDude]

This looks very cool can't wait to try this

--- posts merged. Please don't make me do this, I have a family ---

Hmm got this working, which is awesome, have a question though, is there any way to make the unit recoverable as its spawner. For instance if it was pokemon or turret, and that unit survived you'd want to reuse it. Any ideas?

[Solarius Scorch]

Hmm got this working, which is awesome, have a question though, is there any way to make the unit recoverable as its spawner. For instance if it was pokemon or turret, and that unit survived you'd want to reuse it. Any ideas?

It certainly works for civilians, just like with civilians who spawn normally:

Code: [Select]

units:
  - type: STR_COUNCIL_MEMBER
    civilianRecoveryType: STR_COUNCIL_MEMBER

I haven't tried it with the other sides.

[SuperCaffeineDude]

Ah I see where I went wrong sorry, I was using a pre-existing unit, so instead I need to create my own recoverable unit, thanks!

[ohartenstein23]

Yes, this will work for neutral/civilian units, but unit/corpse recovery is specifically disabled for player-controlled units spawned in this manner.

[Alex_D]

Thus technically, for example, a mod can be implemented where the unit carries a player-controlled micro-UAV, that would allow terrain scouting. The UAV can be fired from its own special launcher. After battle it can be recovered and reused again on the next battle. And this won't count towards the unit limit on crafts.

Am I about right or I need more coffee  ?

[ohartenstein23]

No, player-controlled units spawned by this code won't be recovered.  What you can do is make a 'launcher' for the micro-UAVs and then make the 'ammo' that spawns the UAV cost very little, but the reload is expensive enough TUs-wise that you can't do it during battle so you need multiple launchers if you want multiple UAVs.