How-tos

This page lists how to accomplish tasks that are relatively simple and commonly needed, but that touch on multiple areas of the toolset or are difficult to figure out intuitively how to do.

Just collecting ideas at the moment, add headers if you think a how-to is needed on a particular subject.

• 3D control

Run a cutscene from a trigger

!!compile fails in test database due to bad core libraries, so this hasn't been tested!!

Create a script:

#include "events_h"
#include "global_objects_h"
#include "utility_h"

void main ()
{
    event ev = GetCurrentEvent();
    int nEventType = GetEventType(ev);
    int nEventHandled = FALSE;
    switch (nEventType)
    {
    case EVENT_TYPE_ENTER:
         {
         object oCreature = GetEventCreator(ev);
         if(IsPlayer(oCreature)) { 
              resource rCutscene = R"my_cutscene.cut";
              CS_LoadCutscene(rCutscene);
              DestroyObject(OBJECT_SELF, 0);
         }
         break;
    }
    if (!nEventHandled) //If this event wasn't handled by this script, let the core script try
    {
        HandleEvent(ev, RESOURCE_SCRIPT_TRIGGER_CORE);
    }
}

And set it as the event script for the trigger that you want to have run the cutscene.

Add a follower to the player's party

if(IsPlayer(oCreature)) {
  object oFollower = GetObjectByTag("myfollower");
  UT_HireFollower(oCreature, oFollower);
 }

Have an enemy play possum and then get up to fight

Set the creature's CREATURE_SPAWN_DEAD variable to 2.

When it's time for the creature to rise and attack, execute the following script commands:

#include "wrappers_h"
...
WR_SetObjectActive(oCreature, TRUE);
SetCommandable(oCreature, TRUE);
// Make sure to set this flag back to 0 to avoid problems with savegames.
SetLocalInt(oCreature, CREATURE_SPAWN_DEAD, 0);
UT_CombatStart(oCreature, oPC);

Insert content into an existing area

If you want to add new content on to an existing area (for example, putting a new character or area transition door into an area that exists in the single-player campaign) there are two different ways to do it. One is to override the existing area with a new area of your own design that duplicates the original with the exception of your additions. This is straightforward to do but can interact poorly with other add-ons - you can only have one version of an area active at a time.

A more elegant and extensible approach is to use a PRCSCR_-prefixed M2DA. The PRCSCR M2DA has a very simple structure and a simple but profound effect:

• ID - a unique integer identifier for each row
• AreaListName - a string that identifies a specific area list, or the special keyword "any".
• Script - the name of a script file.

Whenever a player enters an area in an area list in this M2DA the associated script will be run. A modder can therefore include a script with his mod that will be run when the player enters an existing area that he didn't create. This script can freely add or remove placeables and creatures and perform whatever other modifications to the area that a script is capable of doing.

Note that the script will be run every time the player enters the area, so you'll want to have an associated plot flag to ensure that the changes are only made once.

The following example is a script that adds a new character from an add-on module to an existing area in the main game:

void main()
{
    //Check whether we've added Joblo already.
    if (WR_GetPlotFlag("joblos_quest", JOBLO_ADDED_TO_TOWN) == FALSE)
    {
        object oTown = GetObjectByTag("lot100ar_lothering"); //An area's tag is the same as its resource name
        vector vJobloLocation = Vector(126.745f,120.724f,0.460568f); // See below for how to get these coordinates

        CreateObject(
            OBJECT_TYPE_CREATURE,
            R"joblo.utc",
            Location(oTown, vJobloLocation, 180.0f) //See below for how to get the value for orientation
        )

        WR_SetPlotFlag("joblos_quest", JOBLO_ADDED_TO_TOWN, TRUE);
    }
}

Since you can't add waypoints to an existing area you'll need to enter the position and orientation values for the target location manually. You can find them by creating a local copy of the area in question and temporarily adding a waypoint to copy down the coordinates and orientation you'll need.

Add new music

Open up FMOD

It creates a project - set the build directory to your DA override directory - with project highlighted, it is over on the top right about half way down the project settings. You can set a default resource directory but that will just set where the file browser defaults to so it is optional. I'd also define a name in those parameters while you are there.

From there, you need a new event !!(not sure whether a blank default is generated or whether you have to right click and make a default blank event)!!. After you have an event, highlight it and change to the event tab (2nd tab). Here you need to import your file to link to that event.

On that tab I think it creates a empty row for your new event - right click and add wavetable or something like that - I think I use the top option. (Again, might be wrong but the basic goal is getting a audio file in that screen that plays when you hit the play button at the top)

Browse to your wav file or whatever you have.

From there you should be able to play the sound both in the pop-up box and (once that is closed) back in the event tab. You'll see the name of the wave in that once empty row (IIRC).

If you want, you can add layers of sounds to this event using the same process over and over, but keeping it simple; we'll just move along.

Now you have a project and an event. You can set various parameters on the first tab that alter pitch etc on the first tab. (When you import the sound, you set whether it is a one shot or looping).

Once you have that done, go to the top drop down and find build. Build the files and you should see extra files in your override directory.

From there, just open up the toolset (or hit refresh from within the toolset) and your project and event sounds should show up in the listing of sounds.

You can then drag and drop them into the game or cutscene and they will play.

Adding music to cutscenes

The way we have been doing the music changes is via placed sound objects. These sound objects are generally created in FMOD, and in FMOD you can say if the music will persist after the cutscene or end when the cutscene ends.

We are just using other sounds to switch music tracks. Designers can add music switch parameter to any sound in Fmod Designer, usually this is just VO line to change music track, for example:

If there are no other sounds, designers can create empty sound event and add #music parameter there and place this sound on cutscene timeline. Music track has to be defined in the same group as music in current area in “music.fdp” to work.

 #music:name,1 – non looping, for stingers
 #music:name – for looping music

Delete resources

Resource deletion can sometimes be a bit complicated. Check the following:

• Resources must be checked in when deleted. This is so that the toolset can be sure that all dependencies have been properly resolved.
• If other resources reference the resource it can't be deleted. This means that sometimes you'll need to delete resources in a specific order. For example, you can't delete a creature that's being used in an area, but you could delete the area and then delete the creature. Occasionally there may be circular references that you'll need to break by editing the resources before deleting them. For example:
  • A stage can reference an area, which can then reference the stage.
  • A plot file can have an associated event script, which will almost certainly include the plot file.
  • A stage can reference a creature, which references a dialogue, which references the original stage.