CreateObject(int, string, location, int, string)

Create an object of a specified type at a given location

object CreateObject(
    int nObjectType,
    string sTemplate,
    location lLocation,
    int bUseAppearAnimation = FALSE,
    string sNewTag = ""
);

Parameters

nObjectType

nObjectType: OBJECT_TYPE_ITEM, OBJECT_TYPE_CREATURE, OBJECT_TYPE_PLACEABLE, OBJECT_TYPE_STORE, OBJECT_TYPE_WAYPOINT

sTemplate

The resref of the object to create from the pallet

lLocation

The location to create the object at

bUseAppearAnimation

If TRUE, it will play EffectAppear() when created - the creatures appear animation will play (Default: FALSE)

sNewTag

If this string is not empty, it will replace the default tag from the template (Default: "")

Description

This function allows the creation of specific objects at any location within a module.

Using this function it is possible to spawn items, creatures, placeables and stores on the occurance of certain events.

In older patches, providing an invalid sTemplate, a badger would be created when trying to make a creature, and a Miscellaneous Small item when trying to make an item. Confirmed as of patch 1.30, this is no longer the case - an invalid sTemplate will simply not create anything!

Note that you can't use DelayCommand with this function, since DelayCommand only works with void returning functions, and CreateObject returns the created object. Instead, you must create a wrapper function and delay that. BioWare has already provided us with such a wrapper function in an include file: it is called CreateObjectVoid.

Remarks

Only the following constants are valid for the nObjectType parameter:
- OBJECT_TYPE_ITEM
- OBJECT_TYPE_CREATURE
- OBJECT_TYPE_PLACEABLE
- OBJECT_TYPE_STORE
- OBJECT_TYPE_WAYPOINT (as of patch 1.30)

If sNewTag is specified (other than the default ""), the created object will be given that new tag.

Be careful with 'sTemplate', or you may find yourself with a lot more Badgers than you want. A ResRef is a unique key into the palette of objects that comes with the engine and your module. If you attempt to look up the ResRef of a standard placeable or creature, it's natural to right-click the object in the palette and look for a 'Properties' option to examine. It isn't there, and the next-best-thing is very tempting - 'Edit Copy'. Sure enough, 'Edit Copy' gives you the appropriate object properties dialogue, and there's a blueprint ResRef, for example "SKELETON001".

Unfortunately, the Toolset has done what it said it would - shown you a copy of the blueprint, not a copy of an object created using blueprint, as you might expect. So your ResRef is in fact a toolset-generated reference string for a new blueprint - one which promptly disappears when you cancel the properties screen to go back to the Script Editor. To make matters that little bit more confusing, by default the Tag of an object created from a standard blueprint is the same as the blueprint ResRef, which might lead you to mistake a Tag for a ResRef.

The easiest way to find the ResRef for a resource is to click on the "View" menu and select the "Show Preview Window" menu item. This will cause a preview window to appear which details not only the ResRef, but the Name, Tag, and Comments for a particular resource (when available). You can view properties by clicking on an already existing object or choosing an object from the various palettes within the toolset.

Known Bugs

As of patch 1.30, bUseAppearAnimation finally works, though there’s been reports that some of the appear animations are a little weird.

According to Bioware, there was a problem creating waypoints with mappins. This is not mentioned in the release notes for patch 1.31. The problem still persists in 1.61.

Creating a creature during the OnEnter event without first checking to see what's actually entering the area causes NWN to enter an infinite loop of creating creatures (as each creature created causes the OnEnter event to fire its attached script again). This can be avoided by testing if GetIsPC(GetEnteringObject()) is true (if its true, then create the creature(s); if its false then a creature that was created fired the event).

Version

1.62

Example

// The following script will create a chicken next to waypoint.
// The waypoint used is tagged "CHICKEN_WAYPOINT".

// The deadly chicken is from the standard pallet. There are lists
// of creatures Res Refs for standard pallet creatures in the lexicons
// lists, with explanations of what they spawn.

// Note that this deadly chicken shouldn't be created from an area's
// On Enter event, unless there are checks making sure that no
// more then one deadly chicken can be created.

void main()
{
    // Object type to create
    int nObjectType = OBJECT_TYPE_CREATURE;

    // What to create - a "standard" chicken (noting its deadly 1d2
    // damage attack - not what I'd call standard, eh? more like
    // death incarnate for those who annoy it...)
    string sChicken = "nw_chicken";

    // Where to make the chicken appear
   location lTarget = GetLocation(GetWaypointByTag("CHICKEN_POINT"));

    // We do want appear animation
    //  - flying down to our chicken point!
    int bUseAppearAnimation = TRUE;

    // Actually create the object. Note the example below will
    // actually use the object later on, not just call it.    
    CreateObject(nObjectType, sChicken, lTarget, bUseAppearAnimation);
}

// Example 2 will take similar parameters to the above (using 
// some more directly into the function), but once
// the chicken has appeared, it will make it super chicken, 
// by making it god - giving it the power of Plot Mode (TM)

// (Plot mode is a trade mark of the Bioware God and Godess 
// society, Canada)

void main()
{
    // It might look the same chicken...
    string sChicken = "nw_chicken";

    // ...which will appear at the same place...
   location lTarget = GetLocation(GetWaypointByTag("CHICKEN_POINT"));

    // ...and be created the same way...   
    // (Note: we now use a declared object to capture the new 
    // created chicken)
    object oChicken = CreateObject(OBJECT_TYPE_CREATURE, sChicken, lTarget, TRUE);

    // ...but we make it Super Chicken now we created it!
    SetPlotFlag(oChicken, TRUE);
}

// Example 3.
// We create an object using a delayed function. 
// * You can also see CreateObjectVoid() for this function's use.
// Note that this:
/*
void main()
{
    // Chicken again.
    string sChicken = "nw_chicken";
    // Chicken point.
   location lTarget = GetLocation(GetWaypointByTag("CHICKEN_POINT"));

    // Will not work - DelayCommand() requires a "void" function.
    DelayCommand(50.0, CreateObject(OBJECT_TYPE_CREATURE, sChicken, lTarget, TRUE));
}
*/
// ...Will not work, as DelayCommand() will only work if the
// function has "void" or "action" in front of it, for example, 
// ApplyEffectToObject() will work, it has been declared by Bioware
// as "void ApplyEffectToObject(int nDurationType, effect eEffect, object oTarget, float fDuration=0.0f)"

// So therefore, we use this void function to delay the creation
// of our chicken; we won't make him god this time however.

void CreateObjectVoid(int nObjectType, string sTemplate, location lLoc, int bUseAppearAnimation = FALSE)
{
    CreateObject(nObjectType, sTemplate, lLoc, bUseAppearAnimation);
}

void main()
{
    // Chicken again.
    string sChicken = "nw_chicken";
    // Chicken point.
   location lTarget = GetLocation(GetWaypointByTag("CHICKEN_POINT"));

    // Will work - we use new void declared function.
    DelayCommand(50.0, CreateObjectVoid(OBJECT_TYPE_CREATURE, sChicken, lTarget, TRUE));
}

functions:	ActionCreate \| CopyObject \| CreateObjectVoid
categories:	Item Creation Functions
constants:	OBJECT_TYPE_* Constants