MetaTarget definition

Эта страница доступна на Русском

Get MetaTarget

MetaTarget controller:GetMetaTarget(string name)

MetaTarget controller:GetMetaTarget(Entity ent)

MetaTarget controller:GetMetaTarget(table entities)

Returns the MetaTarget struct, which represents a set of entities with the specified name, or passed entities.

Note that for creating Lua outputs, the entity targetname doesn't matter at all.

You can call this function at any time, in any code, as long as you pass an entity or a list of entities directly. Otherwise, if you use a name, you need to ensure that your code is called inside the OnMapLogicInitialized hook.

In another way, you will need to manually create a name cache using controller:CacheEntNames() and then clear it with controller.cache = nil. For a single use it is better to call controller:GetMetaTarget(ents.FindByName(name)).

Arguments

string name; Entity ent; table entities

• The Hammer targetname of the entity. Also can be the Entity itself or a list of entities.

Returns

MetaTarget

• A sequential table of all found entities. The table has specific meta.

MetaTarget

An object that represents a set of entities with the specified name, and provides quick access. This structure consistently stores the entity in itself. Therefore, you can get the entity directly via target[i]. If there are no entities with this name on the map, then the table is empty #target == 0, and calling IsValid(target) will return false.

When we call a method on this object, MetaTarget forwards this call to the nested entities, excluding numbers. A numeric key is getting an entity by its ordinal number.

Note that MetaTarget does not return the result of calling methods, because you are trying to get a value from different entities. You need to explicitly refer to the entity local pos = target[1]:GetPos().

When we try to assign a new variable MetaTarget, it perceives this as an attempt to create a new output. Therefore, the code target.OnPressed = function() end actually creates an output for nested entities. You cannot add variables to the MetaTarget object without bypassing the meta, so the code target.myVal = true is an mistake, it will not work as you expect, but will create a non-existent output myVal. You can bypass the meta using rawset.

Variables

string MetaTarget.name

• The entities name for which MetaTarget was created. If you use an entity or a list, the name can be an empty string. The name of the first entity is taken from the list.

Entity MetaTarget.controller

• The controller entity that this MetaTarget belongs to.

integer MetaTarget.nextOutputId

• Sets a unique output id, this allows you to create independent callback functions. After the output is created, it is reset to the default value 1.

number MetaTarget.nextOutputDelay

• Sets the delay value for the next created output. After the output is created, it is reset to the default value 0.

integer MetaTarget.nextOutputRepetitions

• Sets the max times to fire value for the next created output. After the output is created, it is reset to the default value -1. The value 0 is the same as -1.

Please refrain from using variables nextOutputId, nextOutputDelay, nextOutputRepetitions with MetaTarget, as they are designed to support methods Entity.AddOutput Entity.RemoveOutput Entity.GetOutputs methods.

Methods

boolean MetaTarget.IsValid()

• Returns true if at least one nested entity is valid and the controller is valid. Returns false if there were no entities at all or all of them were removed, or the controller was removed.

Lua outputs

You create a function, specify the variable name (key) as the output name of the entity. Different entities have different outputs, you need to look at output names on the Valve Developer Wiki.

button1.OnPressed = function(ent, activator, caller, value)
	-- use ent instead button1 or button1[1]
	ent:EmitSound("buttons/button24.wav")
end

Be careful not to use the MetaTarget inside the output callback, this will force to call the method on all nested entities, instead of calling it for the one that fires the output.

In most cases, caller is the entity ent itself, but individual outputs can override it. See Keywords notes and special cases. So for example, if you create an OnLockedUse output for func_door, then activator and caller will be a player.

Some entities works incorrectly with outputs, and instead of the player activator will entity ent itself. So for example, if you create an OnOpen or OnClose outputs for func_door, then activator and caller will be this door. This is an engine error.

MetaTarget.OnOutputName(Entity ent, Entity activator, Entity caller, any value)

Arguments

Entity ent

• The entity on which this output is was fired. Since there can be several nested entities, you need to use this variable to access the entity directly.

Entity activator

• The entity that started the events sequence. If the button was pressed by a player, then the player will be here. If you manually started button1:Fire("Press") and didn't pass the activator argument, then there will be NULL.

Entity activator

• The entity that directly fires the output. For example, the button that was pressed.

any value

• If the output has a generated parameter, this value is passed here as string, number or boolean. For example, momentary_rot_button > Position or math_counter > OutValue. In all other cases, it will be nil.