GetFirstRef

A function added by the Fallout Script Extender.

Description

Returns the first reference in the player's current cell. A type can optionally be supplied by its 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.

Syntax

[help]

(ref) GetFirstRef FormTypeID:int CellDepth:int IncludeTakenRefs:bool

Example

Suppose you want to make all the humans in a cell dance?

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

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. GetFirstRef should be before the loop starts (outside it), whilst GetNextRef 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
• GetRefs (to return an array)