Difference between revisions of "AddForm - FormList"
imported>DavidJCobb (→Notes: created refs aren't made persistent by membership in form lists!) |
DavidJCobb (talk | contribs) |
||
| (7 intermediate revisions by 2 users not shown) | |||
| Line 23: | Line 23: | ||
== Notes == | == Notes == | ||
=== Order of items in the list === | |||
FormLists are divided into three sections. First are any forms that were created during play (form ID starts with 0xFF) and were added to the FormList by scripts. Next are all of the forms that are initially present in the FormList per its definition in the Creation Kit. Last are any forms that were not created during play (form ID does not start with 0xFF) and were added to the FormList by scripts. This means that FormLists will not necessarily store forms in the order they were added to the list. | |||
Consider a FormList that has forms ''A'', ''B'', ''C'', and ''D'' added to it in the Creation Kit. | |||
If a script adds forms ''E'', ''F'', and ''G'' to the list (assuming those forms weren't created during play), then the list will contain: ''A B C D E F G''. Now suppose the user saves the game, updates a mod, and then reloads the game. Suppose that that mod update, in the Creation Kit, adds form ''H'' to the end of the FormList. In-game, after the user loads their save file, the list will contain: ''A B C D '''H''' E F G''. | |||
Now, consider a FormList that has forms ''T'', ''U'', and ''V'' added to it in the Creation Kit. | |||
Suppose a script adds forms ''W'', ''X'', ''Y'', and ''Z'' to the FormList; however, forms ''W'' and ''X'' are forms that were created during play (e.g. ObjectReferences spawned via PlaceAtMe), while forms ''Y'' and ''Z'' are forms defined in the user's load order. The FormList will now contain: ''W X T U V Y Z''. | |||
One last detail. Suppose a FormList initially contains ''A'', ''B'', and ''C'', and a script adds ''D'', ''E'', ''F'', and ''G'' to it; the FormList therefore contains ''A B C D E F G''. Now, suppose the user saves the game and updates a mod, and the mod update adds ''G'' to the FormList. What happens? Does ''G'' end up in the list twice, and if not, which position does it use? Well, when the user loads the game, the FormList will be initialized to contain ''A B C G''; then, the script-added forms from the savedata will be imported into the list, avoiding duplicates (the same underlying function is used for this part of savedata loading as for the AddForm function itself). This means that the FormList will end up containing ''A B C G D E F''. | |||
Reverse-engineers should be aware that in memory, the list of non-temporary forms comes before the list of temporary forms; however, the underlying function for [[GetAt - FormList]] checks the latter first, treating the start of the latter as index 0. | |||
=== Other notes === | |||
* FormLists cannot contain duplicate entries. Using AddForm(...) with a form that is already in the list will not add a second copy to the list. | * FormLists cannot contain duplicate entries. Using AddForm(...) with a form that is already in the list will not add a second copy to the list. | ||
* A created reference does not become persistent by virtue of being added to a FormList. If you try to retrieve the reference from the FormList when it is not loaded and not persistent, you will get an incorrect result or no result. | * A created reference does not become persistent by virtue of being added to a FormList. If you try to retrieve the reference from the FormList when it is not loaded and not persistent, you will get an incorrect result or no result. | ||
Latest revision as of 20:13, 9 March 2022
Member of: FormList Script
Adds the given form to the form list.
Syntax[edit | edit source]
Function AddForm(Form apForm) nativeParameters[edit | edit source]
- apForm: Form to add to the list, if apForm == None this function seems to have no effect
Return Value[edit | edit source]
None
Examples[edit | edit source]
; Adds the diamond to the gem list
GemList.AddForm(Diamond)Notes[edit | edit source]
Order of items in the list[edit | edit source]
FormLists are divided into three sections. First are any forms that were created during play (form ID starts with 0xFF) and were added to the FormList by scripts. Next are all of the forms that are initially present in the FormList per its definition in the Creation Kit. Last are any forms that were not created during play (form ID does not start with 0xFF) and were added to the FormList by scripts. This means that FormLists will not necessarily store forms in the order they were added to the list.
Consider a FormList that has forms A, B, C, and D added to it in the Creation Kit.
If a script adds forms E, F, and G to the list (assuming those forms weren't created during play), then the list will contain: A B C D E F G. Now suppose the user saves the game, updates a mod, and then reloads the game. Suppose that that mod update, in the Creation Kit, adds form H to the end of the FormList. In-game, after the user loads their save file, the list will contain: A B C D H E F G.
Now, consider a FormList that has forms T, U, and V added to it in the Creation Kit.
Suppose a script adds forms W, X, Y, and Z to the FormList; however, forms W and X are forms that were created during play (e.g. ObjectReferences spawned via PlaceAtMe), while forms Y and Z are forms defined in the user's load order. The FormList will now contain: W X T U V Y Z.
One last detail. Suppose a FormList initially contains A, B, and C, and a script adds D, E, F, and G to it; the FormList therefore contains A B C D E F G. Now, suppose the user saves the game and updates a mod, and the mod update adds G to the FormList. What happens? Does G end up in the list twice, and if not, which position does it use? Well, when the user loads the game, the FormList will be initialized to contain A B C G; then, the script-added forms from the savedata will be imported into the list, avoiding duplicates (the same underlying function is used for this part of savedata loading as for the AddForm function itself). This means that the FormList will end up containing A B C G D E F.
Reverse-engineers should be aware that in memory, the list of non-temporary forms comes before the list of temporary forms; however, the underlying function for GetAt - FormList checks the latter first, treating the start of the latter as index 0.
Other notes[edit | edit source]
- FormLists cannot contain duplicate entries. Using AddForm(...) with a form that is already in the list will not add a second copy to the list.
- A created reference does not become persistent by virtue of being added to a FormList. If you try to retrieve the reference from the FormList when it is not loaded and not persistent, you will get an incorrect result or no result.