GetFirstRef

A command for Oblivion Script Extender

Syntax:

(reference:ref) GetFirstRef type:short cellDepth:short includeInactiveRefs:short

Returns the first reference in the current cell; use with GetNextRef to scan all of the cell's references.. A type can optionally be supplied to return only references matching that type. Additionally, you can pass 69 for actors and 70 for inventory items. 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.

Example

ref pDoor
...
set pDoor to GetFirstRef 24 1
while (pDoor)
  ; do something with pDoor
  set pDoor to GetNextRef
loop

Scans the list of doors in the player's current cell and the surrounding 8 cells.

Notes

• References can be added to or removed from a cell between frames; for this reason GetFirst/NextRef should be used within a loop that executes within a single frame.
• The order of references as returned by GetFirst/NextRef is essentially undefined. It is not guaranteed that it will remain the same from one frame to the next. As stated above, a loop should be used each time. Usually, however, the first ref is the most recently placed one. It is altogether unwise to rely on this, however.
• The syntax and function has changed between v13 and v14:
  • The includeInactiveRefs flag was added.
  • In v13, inactive references were included (as if the flag was set to 1). This would include items that have been picked up and are no longer in the world.

Form Type IDs

 0:    None
 1:    TES4
 2:    Group
 3:    GMST
 4:    Global
 5:    Class
 6:    Faction
 7:    Hair
 8:    Eyes
 9:    Race
10:    Sound
11:    Skill
12:    Effect
13:    Script
14:    LandTexture
15:    Enchantment
16:    Spell
17:    BirthSign
18:    Activator
19:    Apparatus
20:    Armor
21:    Book
22:    Clothing
23:    Container
24:    Door
25:    Ingredient
26:    Light
27:    Misc
28:    Static
29:    Grass
30:    Tree
31:    Flora
32:    Furniture
33:    Weapon
34:    Ammo
35:    NPC
36:    Creature
37:    LeveledCreature
38:    SoulGem
39:    Key
40:    AlchemyItem
41:    SubSpace
42:    SigilStone
43:    LeveledItem
44:    SNDG
45:    Weather
46:    Climate
47:    Region
48:    Cell
49:    REFR
50:    ACHR
51:    ACRE
52:    PathGrid
53:    WorldSpace
54:    Land
55:    TLOD
56:    Road
57:    Dialog
58:    DialogInfo
59:    Quest
60:    Idle
61:    Package
62:    CombatStyle
63:    LoadScreen
64:    LeveledSpell
65:    ANIO
66:    WaterForm
67:    EffectShader
68:    TOFT
69:    Actors
70:    Inventory items

See Also

• GetNextRef
• GetNumRefs
• HasBeenPickedUp
• GetObjectType