the Sim Settlements forums!

Register a free account today to become a member! Once signed in, you'll be able to participate on this site by adding your own topics and posts, as well as connect with other members through your own private inbox!

Keywords > ActorValues


Well-Known Member
Staff member
Verified Builder
So this is kind of a BS title as the two are used for very different things. (For the record, a lot of these titles are coming from my shorthand notes to myself so that I stop making dumb mistakes.)

Unfortunately, while they should be very powerful, ActorValues have very narrow usage. An ActorValue essentially allows you to assign a float to any object via the SetValue function (you retrieve the value with GetValue). This can be useful for codifying any sort of information you need on a reference for access later, even if you don't have that reference persisted.

Actually, that's a lie - and is the reason why they are so narrow - and inferior to keywords.

If you attempt to fetch a value from a reference that is not being persisted, or is currently disabled, it will return 0. Given that there's no way to distinguish if that's an actual 0, or a mistake because the item isn't loaded, is a problem - there is no NULL in papyrus. The value is still stored on the ref, you just can't access it until the player gets close enough to load the cell again.

So generally, you can only count on ActorValues for objects you know are loaded (Is3dLoaded is your best test to confirm). For many things this is fine, but if you're working on systems like I tend to, you often are working with things all over the game world. I've mentioned several times that persistence solves this, but you really can't just persist every object reference or you will quickly grind the game to a halt.

Why Mention Keywords At All?

Keywords are a little more binary. You can essentially just use them as tags to see if an object has them or not (via the HasKeyword function). So you definitely can't get the same power as AVs unless you're very determined (for example, you could set up a series of keywords to represent flags and treat them like a binary system... don't do that)

They have three key benefits over ActorValues:

1. They will properly return true or false no matter where the reference is, or what state it is in.
2. They can be tested on forms as well as references.
3. They can be used with several Find functions to grab groups of references that are all tagged with them.

Number 2 is especially useful in a situation like Sim Settlements, which is heavily expandable by other authors - so having a method to test items for a property before even creating the reference provides a lot of control.

Number 3 is incredibly powerful for speed reasons, as the closest approximation to it would be using the Find function with a formlist (which is really slow - formlists in general are slow as dirt and should only be used as a last resort or to make something very open - likely a future post...). If you plan ahead and tag similar items that you might like to scoop up together (for example, I tag all plots with a specific keyword, even though each plot type is a different form - I can still grab them all.)

Number 3 is probably also why I think of the Keywords and ActorValues at the same time. One of the most common things to do in settlement related scripting, is to grab item references to do things to them with code - and grabbing them via keyword is much more reliable than via ActorValue (which you can do with a special workshop function called GetWorkshopResourceObjects).

So they're two different things - but Keywords have almost no corner cases that will bite you in the butt later (at least not that I've found so far...). So that shorthand note of Keywords > ActorValues is basically a reminder to myself that I can use Keywords like crazy, but I should be very skeptical about using ActorValues.
Last edited: