Editing GetFirstRef

{{Function
 |origin = FOSE1
 |summary = Returns the first reference in the player's current cell. A type can optionally be supplied by its [[Form Type IDs|ID code]] to return only references matching that type. For example, you can pass 200 for actors and 201 for inventory items. Returns nothing (zero) if there is no ref matching the type in the cell. This function will normally be used only prior to a loop including [[GetNextRef]] to scan actors in a cell.

An optional cell depth can be supplied to specify the number of adjacent cells to scan in exteriors: a cell depth of 1 scans the player's current cell plus 8 adjacent cells, a depth of 2 scans the player's cell plus 25 adjacent cells.

By default, inactive references to items which were previously picked up by an actor are ignored; passing 1 for the third parameter will force those references to be included.
 |name = GetFirstRef
 |returnType = ref
 |arguments = 
  {{FunctionArgument
   |Name = FormTypeID
   |Type = int
   |Optional = optional
  }}{{FunctionArgument
   |Name = CellDepth
   |Type = int
   |Optional = optional
  }}{{FunctionArgument
   |Name = IncludeTakenRefs
   |Type = bool
   |Optional = optional
  }}
}}
==Example==
Suppose you want to make all the humans in a cell dance?
<pre>
ref rActor
set rActor to GetFirstRef 200 ; * 200 == actors
while rActor != 0
    if rActor.GetDead || rActor.GetDisabled || rActor.GetIsCreature
        ; skip
    else
        rActor.PlayIdle MyDancingIdle
    endif
    set rActor to GetNextRef ; * make sure this is within the loop or CTD
loop
</pre>

This script grabs the first actor in the cell, and makes them dance if they are a living, enabled, human. It then repeats this for every other actor in the cell
==Notes==
*The function will pick up dead and disabled references, note the example checks for this.
*Infinite loops immediately crash the game, so make sure you avoid this. <b>GetFirstRef</b> should be before the loop starts (outside it), whilst <b>GetNextRef</b> must be within it (it must run before it repeats).
*At one point the OBSE version of this function had a bug which was commonly worked around by using 'set rActor to Pencil01' immediately prior to 'set rActor to GetNextRef'. A fix was added, so that this workaround should no longer be necessary.
==See Also==
*[[GetFirstRefInCell]]
*[[GetNextRef]]
*[[While]]
[[Category:Functions_(FOSE)]]