Difference between revisions of "BuildRef"
Jump to navigation
Jump to search
imported>Odessa (New page, correct capitalization) |
imported>Odessa m (fixed link) |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 3: | Line 3: | ||
|summary = Takes a mod index as an integer set by [[GetModIndex]] and the decimal converted formID of an object, which may be either a reference or base form, and returns a reference to it. | |summary = Takes a mod index as an integer set by [[GetModIndex]] and the decimal converted formID of an object, which may be either a reference or base form, and returns a reference to it. | ||
This can be used to reference forms contained in non-dependent external modules | This can be used to reference forms contained in non-dependent external modules, but great care must be taken as invalid usage may crash the game. | ||
|name = BuildRef | |name = BuildRef | ||
|returnType = form | |returnType = form | ||
| Line 14: | Line 13: | ||
|Name = DecimalFormID | |Name = DecimalFormID | ||
|Type = int | |Type = int | ||
}} | }}}} | ||
==Example== | |||
<pre> | |||
int iModIndex | |||
ref rRainySmiles | |||
if IsModLoaded "SomePopularCompanionMod.esp" | |||
set iModIndex to GetModIndex "SomePopularCompanionMod.esp" | |||
set rRainySmiles to BuildRef iModIndex, 1068677 | |||
endif | |||
</pre> | |||
== | ==Avoiding CTDs== | ||
If one uses an invalid decimal form ID then it will likely crash the game when you try to use your (mis)built reference. This may be an issue if the form is non existent or different in past or future versions of the referenced module, or if two distinct modules are given the same file name. | |||
You can avoid CTDs by ensuring the return is both a valid form, and of the type you expect it to be, using [[IsFormValid]], and functions like [[IsReference]], [[IsActor]] or [[GetType]]. For example, following on from the code above, where we want to get a companion added by an external mod: | |||
<pre> | |||
if eval !(IsFormValid rRainySmiles) | |||
; The Form is NOT valid, do not proceed! | |||
return | |||
elseif eval !(IsReference rRainySmiles) | |||
; The form is NOT a reference, its something else, do not proceed! | |||
return | |||
elseif eval !(rRainySmiles.IsActor) | |||
; The form is a reference, but NOT an actor (maybe its a door or something)! | |||
return | |||
else | |||
; Its all good, we got an actor from the buildref so we can proceed | |||
endif | |||
; "if eval !(condition)" just means "if conditon is false" | |||
</pre> | |||
Or you can use [[GetType]] for any types: | |||
<pre> | |||
if eval !(IsFormValid SomeBuildRefSpell) | |||
; The Form is NOT valid, do not proceed! | |||
return | |||
elseif GetType SomeBuildRefSpell != 20 ; * 20 is the code for 'spell' | |||
; I was expecting a spell but got something else, do not proceed! | |||
return | |||
else | |||
; Its safe, I got a spell like I expected | |||
PlayerREF.CIOS SomeBuildRefSpell | |||
endif | |||
</pre> | |||
Note: You must use multiple lines for the <b>if</b> statements, not <b>&&</b>, because the GECK always evaluates all conditons on a line. | |||
==See Also== | ==See Also== | ||
*[[FnGetExternalForm]] - A convenient UDF for safe build reffing. | |||
*[[IsModLoaded]] | *[[IsModLoaded]] | ||
*[[GetModIndex]] | *[[GetModIndex]] | ||
*[[GetLocalRefIndex]] | *[[GetLocalRefIndex]] | ||
*[[Causes of CTDs]] | |||
*[[IsFormValid]], [[IsReference]], [[IsActor]], [[GetType]] | |||
*[[Eval]] | |||
[[Category:Functions_(NVSE)]] | [[Category:Functions_(NVSE)]] | ||
Latest revision as of 16:06, 5 April 2015
< [[::Category:Functions|Category:Functions]]
A function added by the New Vegas Script Extender.
Description
Takes a mod index as an integer set by GetModIndex and the decimal converted formID of an object, which may be either a reference or base form, and returns a reference to it.
This can be used to reference forms contained in non-dependent external modules, but great care must be taken as invalid usage may crash the game.
Syntax
(form) BuildRef ModIndex:int DecimalFormID:int
Example
int iModIndex
ref rRainySmiles
if IsModLoaded "SomePopularCompanionMod.esp"
set iModIndex to GetModIndex "SomePopularCompanionMod.esp"
set rRainySmiles to BuildRef iModIndex, 1068677
endif
Avoiding CTDs
If one uses an invalid decimal form ID then it will likely crash the game when you try to use your (mis)built reference. This may be an issue if the form is non existent or different in past or future versions of the referenced module, or if two distinct modules are given the same file name.
You can avoid CTDs by ensuring the return is both a valid form, and of the type you expect it to be, using IsFormValid, and functions like IsReference, IsActor or GetType. For example, following on from the code above, where we want to get a companion added by an external mod:
if eval !(IsFormValid rRainySmiles) ; The Form is NOT valid, do not proceed! return elseif eval !(IsReference rRainySmiles) ; The form is NOT a reference, its something else, do not proceed! return elseif eval !(rRainySmiles.IsActor) ; The form is a reference, but NOT an actor (maybe its a door or something)! return else ; Its all good, we got an actor from the buildref so we can proceed endif ; "if eval !(condition)" just means "if conditon is false"
Or you can use GetType for any types:
if eval !(IsFormValid SomeBuildRefSpell)
; The Form is NOT valid, do not proceed!
return
elseif GetType SomeBuildRefSpell != 20 ; * 20 is the code for 'spell'
; I was expecting a spell but got something else, do not proceed!
return
else
; Its safe, I got a spell like I expected
PlayerREF.CIOS SomeBuildRefSpell
endif
Note: You must use multiple lines for the if statements, not &&, because the GECK always evaluates all conditons on a line.
See Also
- FnGetExternalForm - A convenient UDF for safe build reffing.
- IsModLoaded
- GetModIndex
- GetLocalRefIndex
- Causes of CTDs
- IsFormValid, IsReference, IsActor, GetType
- Eval