PlaceAtMe

Syntax:

PlaceAtMe ItemID, count, [distance], [direction] 

Example:

player.PlaceAtMe Ninja, 1, 256, 1 

Places the object at the calling object, in the direction you specify and the distance. If that location is not safe (in the air, in a wall, etc), the object will be placed at one of the other axes or at the object's exact location.

Direction is:

0 = front

1 = back

2 = left

3 = right

The placed object gets the same XYZ angle values as the calling object. Note that world objects placed at the player will be tilted if the player is looking up or down (player X angle not zero ... object X angle not zero).

This function can be used with leveled creature lists as well.

It can't be used with leveled items, though. Leveled items are not supposed to be placed into the world - you can use them exclusively inside containers. Trying to create an item from a leveled list this way will just cause the yellow exclamation mark (Marker_Error.NIF) to appear.

Warning: Repeated Use Causes Save-Game Bloat

Objects created with PlaceAtMe become part of the savegame file and slightly increase its size. However, those slight increases add up and can become huge when PlaceAtMe is continuously used. Once the savegame file is around 10 megs problems start to creep up, including extended load times, increased game instability and CTDs, and at extreme levels, considerable performance loss and an inability to load the game.

Actor references created using PlaceAtMe, however, are removed upon a cell reset. This happens only to the references that are dead, however recent tests seem to show that living references are removed as well.

As a rule of thumb, it's OK to use PlaceAtMe a finite number of times (i.e., a quest script that runs once and creates 20 PlaceAtMe objects). It's not OK if your script can potentially use PlaceAtMe an infinite number of times (i.e., a Summon spell that creates a new creature with PlaceAtMe, an activator/button that creates a new sword).

With some careful planning, you can use different functions and avoid these problems. For instance, for summonings you can create a persistent creature, place it in a remote cell in the CS, and when the spell is cast use CreatureRef.MoveTo player (note that there's more to summoning, but that avoids the PlaceAtMe problems). If you need an object to appear, create and place it in the CS, make sure it's "Persistent" and "Initially Disabled", and use ObjectRef.Enable.

If you really need to use PlaceAtMe in your mod, it would be fair to indicate that fact in your mod's Readme file.

When running the CS enhanced with Oblivion Script Extender version 18 or later, objects created with PlaceAtMe can be removed by the DeleteReference function.

Getting the Created Object's Reference

When used to create a single object, this function will return a reference to the created object so that it can be used with additional function calls.

Example:

scn scriptName

ref refName

begin blockName
     set refName to refCreatingObject.PlaceAtMe ObjectToBeCreated 1, 0, 0
end

The refName variable will now have a reference to ObjectToBeCreated.

This reference is only reliable for objects that can't be picked up (when they're picked up the reference is destroyed). Accessing the reference of an inventory-item after someone picked it up can cause a CTD.

Note that GetSelf won't return the correct reference when used on PlaceAtMe objects.

Usage in same frame as creation

If you use the referenced item in the same frame as you use PlaceAtMe, that is

set pItem to (player.PlaceAtMe IronBow 1, 0, 0)
pItem.Activate player ;this adds the bow to the player

that item's script may not run. Wait a frame, especially if using Activate.