Building Placeables

Creating placeables under the ACR is nearly the same as creating them under normal NWN, the ACR just provides a few more options for builders.

Naming Conventions

The following conventions will need to be used in naming placeable blueprints to avoid any conflicts with other blueprints and to ensure that all content works properly with scripts:

Localized Name: Choose a one or two word descriptive name. You can add text visible only to builders in {} to help distinguish multiple blueprints of the same type at a glance. Ex: Wooden Chest {trapped}

Template ResRef/Resource Name/Tag: All placeable blueprints in the basemod will begin with the "abr_pl" prefix to designate them as global blueprints. Server specific blueprints should begin with a 3 digit server number in place of the "abr", so "001_pl" for example. For every subcategory, add a two letter acronym delimited with underscores followed lastly by a descriptive name for the placeable itself. This helps to quickly locate blueprints when all we have is its resref. To illustrate, here are a few examples:

• A global container placeable: abr_pl_co_mycontainer
• A server container placeable on server 01: 001_pl_co_mycontainer
• A global building prop: abr_pl_bp_mybuilding

Comments To identify and track blueprint versions, it's best to write your name and the date you modified the blueprint in the comments area. In addition, you may wish to note any scripts the blueprint is specifically used by (primarily for dedicated blueprints). : Ex: Created By: John Doe, Date Modified: 2006/12/20, Used By: acr_placeable_i.nss

For global blueprints, you should also include a link to this wiki page so builders that are unfamiliar with conventions or configuration options can easily find them.

Setting Event Handlers

The default basemod placeables should already have these handlers in place, so if you are copying an existing blueprint, you probably don't need to do anything here. To start off with, make sure the placeable's event scripts are all set correctly. The default scripts are:

• acf_plc_onclosed
• acf_plc_onconversation
• acf_plc_ondamaged
• acf_plc_ondeath
• acf_plc_ondisarm
• acf_plc_onheartbeat
• acf_plc_onlock
• acf_plc_onmeleeattacked
• acf_plc_onopen
• acf_plc_onspellcastat
• acf_plc_ontraptriggered
• acf_plc_onunlock
• acf_plc_onused
• acf_plc_onuserdefined
• acf_plc_oninventorydisturbed

If you wish to make an object (like a chair) sitable, replace the OnUsed event handler with:

• acf_plc_onusedsit

Custom Scripting

If you need to add your own custom scripts, you can of course do so. First, include this line at the top of your script somewhere:

#include "acr_placeable_i"

Then make sure the following functions are called in each of your custom event handlers, just as they are done in the acf_plc_* scripts. Failure to call one of these scripts in a placeable's event handler WILL break the ACR's placeable system, and probably a few other things as well.

• ACR_PlaceableOnClosed()
• ACR_PlaceableOnConversation()
• ACR_PlaceableOnDamaged()
• ACR_PlaceableOnDeath()
• ACR_PlaceableOnDisarm()
• ACR_PlaceableOnHeartbeat()
• ACR_PlaceableOnLock()
• ACR_PlaceableOnMeleeAttacked()
• ACR_PlaceableOnOpen()
• ACR_PlaceableOnSpellCastAt()
• ACR_PlaceableOnTrapTriggered()
• ACR_PlaceableOnUnlock()
• ACR_PlaceableOnUsed()
• ACR_PlaceableOnUserDefined()
• ACR_PlaceableOnInventoryDisturbed()

Configuration Options

See also: Using Local Variables

These options allow the builder to configure a placeable to better suit their needs. These options are changed by altering the local variables on the placeable itself, and not by altering any of the scripts used by the placeable. The default basemod placeables should already have these variables in place, so if you are copying an existing blueprint, you probably only need to alter the values of the variables here.

• ACR_PLC_BREAK_DC (integer) This is the strength-check DC necissary to force open a placeables lock, as per DMG rules. This is generally an alternative to smashing something to pieces with an axe.
• ACR_PLC_AUTO_LOCK (integer) If zero, the placeable behaves normally. If nonzero, it will always lock itself when it shuts.
• ACR_PLC_IS_STUCK (integer) If zero, the placeable behaves normally. If nonzero, it is stuck shut, and must be forced open regardless of whether or not it is locked.
• ACR_PLC_WEIGHT (float) If you want creatures to be able to pick up and move a placeable, set this value. They will be able to pick it up in both hands, and drop it again somewhere else. The placeable takes up both of their free hands, so fighting is not possible without dropping it. If you don't want a placeable to be able to be picked up, leave this value at zero. Note: Movable placeables must be usable, walkable, non-static, and have dynamic collisions turned on.
• ACR_PLC_CARRIED_ITEM (string) If you want a placeable to become a certain type of item when it is picked up, set this string to the resref of that item. If this string is defined, the weight setting will be ignored, and the item's default weight used. When the PC drops this item, the placeable will be created at the dropped location. Note: Movable placeables must be usable, walkable, non-static, and have dynamic collisions turned on.
• ACR_PLC_LIGHT (string) This is the resref of the light object used to "light" the placeable when its light is "on".
• ACR_PLC_LIGHT_VFX (string) This is the resref of the VFX to be used while the placeables light is "on".
• ACR_PLC_LIGHT_ON_HOUR (integer) The hour the placeable turns its light "on". If equal to ACR_PLC_LIGHT_OFF_HOUR (or if neither variable is set), the placeable's light never changes on its own. Valid values are from 0 to 23.
• ACR_PLC_LIGHT_OFF_HOUR (integer) The hour the placeable turns its light "off". If equal to ACR_PLC_LIGHT_ON_HOUR (or if neither variable is set), the placeable's light never changes on its own. Valid values are from 0 to 23.
• ACR_PLC_LIGHT_INITIAL_STATE (integer) Sets the initial state of the placeable's light. If zero, it is off. If nonzero, it is on. If the on/off hours are used, this setting is ignored.
• ACR_PLC_LIGHT_TOGGLE (integer) Sets whether or not a creature can light or unlight this placeable on its own, by using it. If zero, it cannot. If nonzero, it can.

Persistence Options

These options are used make placeable inventories persistent:

• ACR_PSO_NAME (string) Sets the name of the database to which inventory is stored. THIS MUST BE UNIQUE PER MODULE AND HOST.
• ACR_PSO_ONDEATH (integer) Sets whether the inventory of a persistent container should drop when destroyed. 0 = DO NOT DROP (default behavior) 1 = DROP INVENTORY

Conversation Options

In order to make a placeable use a conversation:

• Place the standard script "x2_use_placeable" in the onused script event.
• Check the box on your placeable for 'Usable' and uncheck the box for 'Static', it can be 'Walkable' or not depending on your needs.
• Place the name of the Conversation it will start in the Conversation box.
• Alternately you can also set the 'Default Action Preference' to Use to make it easy for your players to access the conversation.

Effect Options

These are advanced options for placing effects (visual and otherwise) on placeables. For the following effect options, {EVENT} is one of:

• ON_OPEN
• ON_CLOSE
• ON_LOCK
• ON_UNLOCK
• ON_USED
• ON_ATTACKED
• ON_DAMAGED
• ON_SPELLCAST
• ON_SPAWN
• ON_DEATH
• ON_DISTURBED
• ON_HEARTBEAT
• ON_DISARM
• ON_PERCEPTION

The possible configurations are as follows.

EFFECT_VISUAL

ACR_VFX_{EVENT}_EFFECT_VISUAL (string)

These strings are used to define the visual effects that trigger for each event on the activating creature (this includes light shaft placeables). These are not mutually exclusive options (ie they can all be defined on a single object). Each string must be defined in the following format: VFX CONSTANT/VFX DURATION, where VFX CONSTANT is one of the GetEffectInteger constants defined in visualeffects.2da (listed in NWScript.nss) and VFX DURATION is a float representing the total number of seconds the effect should last (use 0.0 if it's either n/a or a permanent effect; some exceptions apply noted in the individual effect sections of the documentation).

Visual effects are those which only provide a visual indicator that something has occurred. These effects are totally harmless but are used in conjunction with Physical and Damage Effects to illustrate something has occurred to the target upon interacting with an object (the source of the effects).

Visual effect constants are string values used in constructing the *_EFFECT_VISUAL local variable. The list of supported effects can be expanded as necessary, but any changes or additions should be reflected in the _getVFXConstant() function in the acr_vfx_i.nss file in order for the effect to function.

Not all visual effects will support variable durations. Some simply have fixed animation cycles which cannot be affected through scripting.

To setup the visual effect local variable, select the object in the toolset that you wish to add effects to then click the "..." button in the properties dialogue to browse the variables list on the object. Once the variables screen opens up, enter in the appropriate variable name for the effect in the name field, select "string" as the variable type, and then enter in the appropriate value.

For example, to construct a fire beam that triggers when an object is used (touched) and expires after 5 seconds, you would create the following:

Variable Name : ACR_VFX_ON_USE_EFFECT_VISUAL

Variable Type : string

Variable Value : VFX_BEAM_FIRE/5.0

You can substitute any of the available visual effects constants in place of VFX_BEAM_FIRE, but be sure your spelling is correct. Typo's will not yield correct results.

EFFECT_PHYSICAL

ACR_VFX_{EVENT}_EFFECT_PHYSICAL (string)

These strings are used to define the physical effects that trigger for each event on the activating creature. These are not mutually exclusive options (ie they can all be defined on a single object). Each string must be defined in the following format: VFX TYPE/VFX DURATION, where VFX TYPE is the specific type of effect to be applied and VFX DURATION is a float representing the total number of seconds the effect should last (use 0.0 if it's either n/a or a permanent effect; some exceptions apply noted in the individual effect sections of the documentation).

Physical effects are those that affect the target's health or condition. These include anything from raw damage to altering the target's state of mind. They typically have NO visual indication (exceptions exist like knockdown) and as a result, should be used in tandem with a suitable visual effect for the benefit of the player (both in terms of providing IC feedback that something has affected their character as well as providing a more enjoyable and engaging atmosphere).

Not all physical effects have durations. Some are instant effects and others are permanent. damage effects apply directly to the physical effect, and as such, you should always reference this section when constructing damage effect values to understand how the damage will be applied.

To setup the physical effect local variable, select the object in the toolset that you wish to add effects to then click the "..." button in the properties dialogue to browse the variables list on the object. Once the variables screen opens up, enter in the appropriate variable name for the effect in the name field, select "string" as the variable type, and then enter in the appropriate value.

For example, to construct a knockdown physical effect to be used with the fire beam visual effect described above that expires after 10 seconds, you would create the following:

Variable Name : ACR_VFX_ON_USE_EFFECT_PHYSICAL

Variable Type : string

Variable Value : KNOCKDOWN/5.0

You can substitute any of the physical effects available in place of KNOCKDOWN, but be sure your spelling is correct. Typo's will not yield correct results.

EFFECT_DAMAGE

ACR_VFX_{EVENT}_EFFECT_DAMAGE (string)

These strings are used to define the damage a physical effect will apply to the activating creature for each event as well as the saving throw required to avoid suffering from the physical effect or related damage. These are not mutually exclusive options (ie they can all be defined on a single object) but they must exist for each physical effect defined if some form of damage is to be applied. Each string must be defined in the following format: DAMAGE/ST TYPE/DC, where DAMAGE is the damage value to apply toward the desired physical effect, ST TYPE is the type of Saving Throw possible (FORTITUDE, REFLEX, or WILL), and DC is the Difficulty Class of the save.

Damage effects contain the actual details of the physical effect being applied, including any saving throws and DCs that the target can attempt to save against. Damage effects need not be defined, but they should be defined appropriately according to the physical effect used. Read the article on physical effect types to determine how damage values are applied to a given physical effect. Do not define a damage Effect without a corresponding physical effect to apply it to.

To setup the damage effect local variable, select the object in the toolset that you wish to add effects to then click the "..." button in the properties dialogue to browse the variables list on the object. Once the variables screen opens up, enter in the appropriate variable name for the effect in the name field, select "string" as the variable type, and then enter in the appropriate value.

For example, to give the knockdown physical effect described above some damage and allow the target a reflex saving throw of DC 15, you would create the following:

Variable Name : ACR_VFX_ON_USE_EFFECT_DAMAGE

Variable Type : string

Variable Value : 3.0/REFLEX/15.0

All values must be represented as floating point numbers.