~~NOTOC~~
<=[[4rpl:start| Index]]\\
<= [[4rpl:start#Unit]]
<WRAP tabs>
  * [[4rpl:commands:getcelloccupiedcount|Get]]
  * [[4rpl:commands:setcelloccupiedcount|Set]]
</WRAP>
:!: Available in version 1.3 and later.
====== SetCellOccupiedCount ======
SetCellOccupiedCount(<-cellX <-cellZ <-count)

===== Description =====
Sets the occupied count for a map cell. Extreme caution must be exercised when using this command. Normally units will increase the count for cells they occupy when they land or are created. The units will also decrease the count by 1 whenever they take off or are destroyed. Messing with the count can create 'phantom' areas on the map where units can't land or where they can stack. Units do not know that you have altered the count! So if you change the occupied count, a unit will still decrease the count by 1 when it takes off or is destroyed.

The effect of SetCellOccupiedCount does not persist between save and loads, as all units rebuild their cell occupied counts whenever the game is loaded and units are rebuilt from the save file.\\
:WARNING: This also applies to using this API in :Gameloaded and :Awake (when game is also loaded). This API will not function as desired should it be called in :Gameloaded or :Awake (:Awake will work fine when placing units, just not when units are loaded in). This is due to the game rebuilding cell occupy counts latter than :Awake and :Gameloaded, causing the effects of this API used in such functions to be overwritten.

If you're trying to make a custom unit occupy cells in a custom shape rather than the default box shape, refer to [[cw4:4rpl_tools#custom_celloccupiedcount_shape|Custom CellOccupiedCount shape]] for a copy-paste ready script that simplifies creating one and handles all of the difficult parts of using SetCellOccupiedCount, including handling unit movement.

===== Examples =====
<code 4rpl>
#Make an area on the map that nothing can land in.
once
   20 10 do
      20 10 do
         SetCellOccupiedCount(I J 10000)
      loop
   loop
endonce


#Make an area on the map always have a count of 0.  This means units can stack on top of each other in this area.
10 0 do
   10 0 do
      SetCellOccupiedCount(I J 0)
   loop
loop 
</code>

<=[[4rpl:start| Index]]