CreateArea(string, string, string)

From NWN Lexicon
Jump to: navigation, search
Nwnee logo.jpg Note: This article documents Neverwinter Nights: Enhanced Edition new content or changes/updates/fixes to 1.69 functions. These are all listed under the category and patches pages.
Creates an instanced copy of an existing area, based on the area's resref.
object CreateArea(
    string sSourceResRef, 
    string sNewTag = "", 
    string sNewName = ""
);

Parameters

sSourceResRef
The source area resref of an area to create a version of.
sNewTag
The new tag of the created area.
sNewName
The new name of the created area.


Description

Instances a new area from the given sSourceResRef resref, which needs to be a existing module area. Will optionally set a new area tag and displayed name. The new area is accessible immediately, but initialisation scripts for the area and all contained creatures will only run after the current script finishes (so you can clean up objects before returning).

Returns the new area, or OBJECT_INVALID on failure.

Note: When spawning a second instance of a existing area, you will have to manually adjust all transitions (doors, triggers) with the relevant script commands, or players might end up in the wrong area.

Note: Areas cannot have duplicate ResRefs, so your new area will have a autogenerated, sequential resref starting with "nw_"; for example: nw_5. You cannot influence this resref. If you destroy an area, that resref will be come free for reuse for the next area created. If you need to know the resref of your new area, you can call GetResRef on it.

Note: When instancing an area from a loaded savegame, it will spawn the area as it was at time of save, NOT at module creation. This is because the savegame replaces the module data. Due to technical limitations, polymorphed creatures, personal reputation, and associates will currently fail to restore correctly.


Remarks

This works very similarly but a little different to CopyArea - notably this uses whatever the base game files were before alteration by the game loading them (although if saved it'll be as it was when the game was saved), while CopyArea will create a copy of the existing area and all changes made since the game loaded it (eg creature spawns and AI movement).

It is usable to create an area in an active server (persistent world) by loading .are (and possibly .gic if you want the instanced information) in the development or override folders of the server dynamically, allowing for DM focused special areas or custom one offs to be added. Additionally CreateArea can be used for instanced player houses or the like.

Previous remarks on save game compatibility are now out of date and this will work with saves, excepting the note above about some limitations with polymorph, personal reputations and associates. It would be recommended to spawn in creatures post-CreateArea rather than have them in the area when it is used for CreateArea.


Version

This function was added in 1.74.8149 of NWN:EE.

Note that the description of this function was omitted from the PDF release notes.  The function is described in a readme in the lang/<language>/docs directory delivered with Neverwinter Nights Enhanced Edition, and in the toolset script editor.

This function was updated in 1.84.8193.29 of NWN:EE. Changes and fixes to how CreateArea and CopyArea are done to have save game compatibility.

Example

Information icon.png This article is in need of examples. You can help the NWN Lexicon by showing how to use this code effectively.

See Also

functions: DestroyArea CopyArea SetTransitionTarget



 author: Shadguy