Scripting Tutorial: Working with FormLists

This article is incomplete. You can help by filling in any blank descriptions. Further information might be found in a section of the discussion page. Please remove this message when no longer necessary.

This article is a WIP. I'll try to finish it in the next few days.--Omzy 00:50, 1 August 2009 (UTC)

IMPORTANT

You will need Fallout Script Extender (FOSE) for this tutorial.

Introduction

With the development of the GECK came several new object types and functions that were not seen in previous versions of Bethesda's game construction kits. One of the new object types that was added is called a FormList. A FormList is, naturally, a list of FormIDs of objects from the editor.

FormLists were originally created to serve a variety of purposes (See FormList). The creators of FOSE developed a handful of new functions that allow easy script manipulation of FormLists. These functions made FormLists much more powerful, giving them the all the functionalities of the List programming construct found in almost all high level programming languages.

In this tutorial, you may see forms described as base forms and reference forms. The difference between the two is that base forms are the object templates from the editor (like a class in C++) and reference forms are instances of these object templates (like an instance of a class). Both base forms and reference forms contain a FormID, so most list functions will not discriminate between the two. However, some list functions may only accept one type as a parameter. See the individual function definitions for more information.

FormList Functions

This table lists the FormList functions currently available to modders:

From the GECK	From FOSE
AddFormToFormList	ListAddForm
IsInList	ListAddReference
IsWeaponInList	ListRemoveForm
	ListRemoveNthForm
	ListReplaceForm
	ListReplaceNthForm
	ListGetNthForm
	ListGetFormIndex
	ListGetCount

Modifying FormLists

The following sections detail some common list operations you might want to perform on your FormLists.

Creating a List

• FormLists must be created in the GECK, as there are no functions at this time to generate them from scripts.

1. Navigate in the Object Window to Miscellaneous -> Form List.
2. Right click, select New.
3. Enter an ID for your FormList.

Adding Forms to a List

• You can add base forms to a FormList in the GECK by dragging and dropping them into the FormList window.
• You can use the ListAddForm function.
• You can use the ListAddReference function.
• You can use the AddFormToFormList function, although it is recommended to use ListAddForm instead since the FOSE function names are more standardized.

Removing Forms from a List

• You can remove forms from a FormList in the GECK by selecting a form and pressing the 'Delete' key.
• You can use the ListRemoveForm function.
• You can use the ListRemoveNthForm function.

Replacing Forms in a List

• You can use the ListReplaceForm function.
• You can use the ListReplaceNthForm function.

Getting Forms from a List

• You can use the ListGetNthForm function.

Getting List Information

• You can view the entries of a FormList in the GECK in the FormList window. In the first column is the index of the entry. In the second column is the type of form (references are REFR). In the third column is the EditorID. In the fourth column is the NumericID.
• You can use the IsInList function.
• You can use the ListGetFormIndex function.
• You can use the ListGetCount function.

Using Lists to Create Floating Text

This example goes beyond what a casual modder might attempt to accomplish, but it displays the abilities of lists quite well.

Suppose we have added 27 textured meshes into the GECK, corresponding to the letters of the English alphabet plus a space character. These meshes are added as forms (e.g. we have objects in the editor letterA, letterB, etc.). Now suppose we want to use these to display a list of names on a sign board in Fallout 3.

We have determined:

• The first letter of the first name should be positioned at (1000,1000,1000) in our cell with angle positions of (0,0,0).
• The offset to the next letter is (0,5,0), meaning if the first letter of a name is at x=1000,y=1000,z=1000 in a cell, the next letter should be at x=1000,y=1005,z=1000.
• The offset to the next name is (0,10,0), meaning if the first letter of the first name is at x=1000,y=1000,z=1000 in a cell, the first letter of the second name should be at x=1000,y=1000,z=1010.
• Our names are (courtesy of FF7):

1. Cloud
2. Tifa
3. Barret
4. Aeris
5. Red XIII
6. Yuffie
7. Vincent
8. Cait Sith
9. Cid

So, let us create a FormList for each name that contains the letters of that name As it would seem, a FormList is also an object in the editor, which has its own FormID. That makes a FormList a Form. What this means is that FormLists can contain other FormLists. This may seem a bit confusing if you've never learned any mid-level programming before, so lets look at the following script and see what it does:

(script here)

(add more scripting tricks/uses)