Frobbing

Player Settings

Cvars

• cv_frob_width: When a ray trace along the line the player is looking does not hit a frobable item directly, a box is created around the item. This setting is 1/2 the width of that box (in doomunits). I.e. it creates a cube with sides of length cv_frob_width * 2. Current default is 10.

NOTE to mappers: Frob can potentially go thru walls up to the frob width. We will eventually tweak this width and when everyone agrees on a setting that's good, we'll lock it in. At that point, make sure not to set anything closer than that distance to the outer surface of a barrier if you don't want it frobbed thru that barrier. Or, if you absolutely must have something closer than that distance, you can turn frobbing on and off on the items with scripting (see below).

• cv_frob_fadetime: The time in milliseconds that it takes the frob highlight to fade in and out completely. Default is 100 [ms].

darkmod.ini

In the "[GlobalParams]" section:

• DefaultFrobDistance=80: This value determines how close you have to be to an item before it will highlight. This value can be overwritten for each item individually (see below) and will only be applied if no value has been specified.

Entity Settings

The following keys control frobbing on individual entities, and should be placed in the entityDef or spawnargs:

• frobable If set to "1", entity is frobable (default is 0)
• frob_distance Distance (in doomunits) at or below which the entity may be frobbed.
• frob_bias When no item is directly hit by the frob raytrace, and several items are within the frobdistance, an item is selected based on how close it is to dead ahead along the center of your view. Setting frob bias biases one item over others in this case, allowing it to be a bit farther off-center but still highlight. This can make it easier to frob small items (like coins) when they are next to larger items. The frob bias multiplies the measure of how close it is to the center of your screen. E.g., a frob bias of 1.5 means you can move your "focus" 50% farther towards another item (which has bias 1.0) and the 1.5 bias item will still be selected. Default is 1.0.
• frobbox_size Takes a single value to set a cube volume whose sides are twice that value centred around the entity origin (not necessarily the centre of its volume) that the player can face and still keep the entity highlighted for frobbing. If too small the player may struggle to pinpoint on the entity and get the frob highlight; if too large then it might conflict with other frobbables nearby and possibly affect performance.
  The default in defined frobbables is 10 which means a box 10 from the centre in each perpendicular direction ie, a box 20 x 20 x 20 doom units centred on the entity origin (see also size below.) In some situations if the margin to get frob focus on an entity seems particularly narrow and difficult then set frobbox_size to 12 or 15. You are unlikely to need to go any bigger. If you create a simple frobbable eg, by just adding frobable 1 to a func_static, then the default frob box is the dimensions of the entity so you should also add frobbox_size else it will be difficult to focus on. Note that the example won't actually do anything when frobbed unless, eg, you frob_peer it to something else.
• size defines a clipmodel which here is used as a frob box. The individual dimensions of the frob box are centred on the centre of the volume of the entity (NOT the entity origin as with frobbox_size above.) eg, 20 10 10 and this might be used to set a non-cube on say a long item like a frobbable pipe. These are not aligned to the world but to the entity. They override the frobbox_size setting. So, assuming an entity whose origin is at the centre of its volume then size 10 10 10 would produce the same cube as frobbox_size 5. size can also produce cone and cylinder shapes - see size
• frobbox_mins Takes three XYZ values to position the 'near bottom left' corner (facing towards positive X of entity alignment) as an offset from the entity origin. Must be used with, and values must be lower than, those in frobbox_maxs.
• frobbox_maxs Takes three XYZ values to position the 'far top right' corner (facing towards positive X of entity alignment) as an offset from the entity origin. Must be used with, and values must be higher than, those in frobbox_mins.
• snd_acquire Name of the soundshader to play when the entity is "used" while frobbed. (NOTE: Maybe we should change the name of this to snd_frob or snd_frobaction or something?)
• frob_action_script String name of the script that will be called when an item is frobbed. Note that you must specify the scope to call the script in. If it's on the same entity, you should use "<name of entity scriptobject>::<function>". Similarly, if the script to call is within the namespace of a map, you should use "<map namespace>::<function>". Otherwise, just inputting "<function>" will call a global scriptfunction.
• frob_peer_<N> Determines what other ents shoud hilight when this ent is hilighted. For each ent you want to hilight, put in a key of the form "frob_peer_<N>" with value: "<entity name>". If you just want one frob peer, putting in "frob_peer" is also fine, but multiple frob peers must have the form "frob_peer_*". NOTE: Currently this only works to propagate the hilight. The frob action when you hit "use" is not propagated to all entities within a frob peer group. This is handled by setting "frob_master" described below.
• frob_master Set to the name of an entity. This is used to propagate the frob action to other entities when one frobbed entity is used. It sets up a chain, and frobbing any link in the chain will call the frobaction on the whole chain.
• inv_frob_distance_cap Max frob distance when acted upon by tool from the inventory, eg, key or lockpick used on door. Default is 40 to force player to move in closer. Can be adjusted for special individual cases, eg, a lock that cannot be quite reached through a gap or window.

Typical Default Values of Frob Distance

by Geep 2021

A review of the entityDefs in the standard distribution reveal some typical frob_distance values.

Category	frob_distance value
Movers in general	100
Doors	Varies: 100, 60, 40
AI	60
Props	40
Readables	56

This table is not definitive, since class inheritance is tricky. "Props" includes things like keys, as well as wearables like arrows in quivers. "Readables" is set to a precise value to be as close as possible while still working with TDM desk models.

Using items on other items

• used_byN <entity name> spawnargs (where N is a number). Some entities can be "used" by one or more other entities. For example, a fountain can be used by a water arrow to make it holy, or a door can have a list of keys that can unlock it (see Doors). Thus, if "door1" had two copies of its key, it might have spawnargs like:

used_by1 key_simple_guards_belt
used_by2 key_simple_on_shelf

To make this work, the prefix "used_by" must be there, followed by either nothing or a unique value of N. (Values of N don't have to be contiguous, and the order of these spawnargs doesn't matter.)

NOTE: An item that can be used on another item (like a key), must also have the spawnArg "usable" set to "1" in order to use it on something else.

Using a target_set_frobable

This is an entity (a single brush) used inside containers (cabinets, drawers, footlockers, etc.) to control when the objects inside it are frobable. Since the player shouldn't be able to frob objects inside the container when its lid or door is closed, frobbing the lid or door tells the target_set_frobable to disable (closed) or enable (open) frobbing of its objects.

The target_set_frobable determines what's "inside" it by checking the frobbox size or collision boundary of nearby objects. If you use these spawnargs on an object: frobbox_size, or the frobbbox_mins & frobbox_maxs pair, it's possible for the target_set_frobable to find objects that really aren't "inside" it. They could be nearby and "outside", but if their frobbox extends into the target_set_frobable, the target_set_frobable will see them and toggle their frobability as needed. This might not be what you want. So if you're having problems frobbing an object, check whether it uses a frobbox and if there are nearby target_set_frobable entities. This is a particular problem with the writing bureau prefab, which has multiple neighbouring target_set_frobable entities; when you think an object is "inside" one of these entities, but it's been assigned to a different one instead.

Below is the forum thread post with a test map made by Bikerdude in response to a key frob problem he had been having with one of his missions. The fix found by Grayman was to reduce the frobbox size on the key to 0. The reason being that the default frobbox size of 10 on the key entity was extending into the target_set_frobable located below where the key was placed.

http://forums.thedarkmod.com/topic/14422-cant-frob-a-key-after-opening-a-drawer/page__view__findpost__p__302991

Another approach is to set the spawnarg immune_to_target_setfrobable 1 on each entity to be excluded from the effect of any nearby target_set_frobable.

Setting Frob From a Script

You can switch the frobability of an object in a script with the command:

$<entityname>.setFrobable(n);

where n is "1" to make it frobable and "0" for unfrobable.

Also, you can simulate a frob action performed by the player thusly:

$<entityname>.frob();

If of interest, that function returns a float value: a boolean TRUE if the entity is frobable, FALSE otherwise.