Built On

The Built On Unit Property in the Data Editor is used to specify which existing units the unit is allowed to be built on. This means that the unit may no longer be built normally and must be constructed on top of one of the units listed. In normal StarCraft II maps, this property is used to require that certain structures be built on top of Vespene Geysers.

Using the Built On property

Creating the bottom unit

To create the base, it is important to copy it from the original Vespene Geyser unit. To do so, right click on the Vespene Geyser unit and click Duplicate Object. The reason we are duplicating the unit is so it will have a copy of the actor and so that it will already have the Gas (Raw Vespene Geyser) behavior, both of which are essential. Click on the check box beside the actor and then click OK.

Now you may edit the unit to suit your needs, but do not remove the Gas (Raw Vespene Geyser) behavior or any events from the actor.

Creating the top unit

To create the top unit, simply create any unit you wish (or modify an existing unit), then give it the Harvestable Vespene Geyser Gas behavior, and edit the Techtree - Built On property to reference the bottom unit you created.

Notes

If you do not want the bottom or top unit to show any resources, you can edit the Stats - Flags property and uncheck Show Resources.

The reason the bottom unit needs to have the Gas (Raw Vespene Geyser) behavior is because currently in StarCraft II, if you try to build on a unit that does not have a resource behavior, the game will crash. The reason the top unit should have the Harvestable Vespene Geyser Gas behavior is so that specific actor events will fire when the top unit is built upon the bottom unit.

Details

Actor events

Behaviour.RawVespeneGas

This event has 3 useful sub names for the Built On property. They are Host Start, Host Finish and Host Clear. Host Start occurs when the top unit begins to build on top of the bottom unit. Host Finish is when the unit finishes constructing, and Host Clear is when the unit is no longer on top of the bottom unit.

Signal.*.Covered and Signal.*.Uncovered

Taking a look at the Assimilator actor, one can see that it has a UnitBirth event, where it creates a "GeyserBuildFinishCovered" actor (or "GeyserUncovered" at removal). (It does that with a 0.1s delay using a timer, for the build-finished version)

Those actors are of type "Region (Circle)", which as a UnitBirth event do a "QueryRegion" actor-event, with System/Self as a region, defining "GeyserBuildFinishCoverQuery" (and "GeyserUncoverQuery") as Query-Response type.

Those responses are actors of type "Query Response", which define a Subject and "On Response" events: The "Subject" uses "Unit" as filter, and a "ScopeContains" Term with the "_Geyser" Alias as parameter. All Geyser actors have "_Geyser" in their Alias list. This seems to limit the unit-types the query response should apply to. As "On Response" event they define a "Signal" event (Scope = QuerySubject), with the "Sub Name" "Covered" (or "Uncovered"), and as target the Alias "_Geyser".

The effect is that the Geyser Actors recieve a "Signal" actor event, with the Sub-Name "Covered". Defining a signal of such a type manually works just as well, and one can add to some actor's events "Signal" event, and have them do some other actor-event from it. Eg. one could add "Signal.BuildFinished" -> "Destroy". Which basically causes the unit you build on to disappear (and not come back unless you recreate it later.)

The only mystery left is how the "Covered" and "Uncovered" Signal-Actor-Events are handled. I have not found any useful way to use these signals.

(My usecase: A base, on which a gem is built, but the base should stay visible. Problem: multiple gems can be placed on the base for some reason... "Covered" or "Uncovered" events are ignored, I have not copied from the vespene actors/units, so that's to be expected.)