func_instance_io_proxy

func_instance_io_proxy is a point entity available in all Source games since Alien Swarm.

Entity description

It is used to forward entity I/O between instances and the rest of the world.

Place one copy of this entity inside of an instance. Sending messages to entities inside the instance from the Proxy's OnProxyRelay output will allow you to trigger these entities from outside the instance by sending messages to the func_instance. Send the ProxyRelay message from entities inside the instance to the proxy and you will be able to use these events to send messages to other entities outside the instance from the func_instance.

Note:The instance, the proxy, and all entities involved should be named descriptively.

Note:This entity is not internal and will remain after compilation.

Bug:

• Entities that send an output to a proxy via ProxyRelay can only output to a proxy. If an entity has outputs to both the proxy and other entities inside the instance, the proxy will re-route the normal outputs to ProxyRelay# and the i/o system will exhibit undesired behavior.
• A Fix Up Name must be explicitly set. If the instance's Fix Up Name is left blank then relaying will not work and entities within the instance will not even show up in the ent_fire command's auto-completion. This is the case even when an instance should get an automatically generated name.
• If an instance is nested within another instance, then sending messages into the instance through a relay will not work. You can work around this by naming entities directly based on known fix up names instead of using the proxy relay.  [todo tested in?]

KeyValues

Name (targetname) <string>

The name that other entities refer to this entity by.

Inputs

ProxyRelay <string>

This message will get relayed and will be available from the instance.

Outputs

OnProxyRelay

A message from outside can trigger this to cause something to happen in the instance.

Note:Both ProxyRelay and OnProxyRelay don't exist for the engine. They're used as a placeholder for VBSP and are automatically mapped onto OnProxyRelay1 to OnProxyRelay30 on compiling.

Usage

Creating Outputs

The most valuable use of func_io_proxy is to map outputs from entities inside an instance so that they become configurable outputs of the func_instance entity itself. Without this function, any interactions with the outside world would need to be carefully planned and predicted, thus greatly reducing the ability for the instance to do anything interesting.

To route an output, you'll need to go into your source entity and send an output to the proxy with a ProxyRelay input such as:

detect_stuff_trigger - trigger_multiple

	My Output >	Target Entity	Target Input	Parameter	Delay	Only Once
	OnStartTouch	door_proxy	ProxyRelay		0.00	No

 

func_instance entities will now be able use this output as if it were one of their own.

Note:Due to a current limitation with proxies, once an ouput has been made to a proxy, that entity will be unable to send any more outputs to entities inside the instance. You may work around this by adding an extra entity to handle the same inputs and functions, but sending its outputs only to the entities inside the instance while the original remains pointed only to the proxy.

If you go to the outputs tab for the func_instance and click add you'll see that you can now select and configure outputs like:

func_instance

	My Output >	Target Entity	Target Input	Parameter	Delay	Only Once
	instance:detect_stuff_trigger;OnStartTouch	zap_sound	playsound		0.00	No
	instance:detect_stuff_trigger;OnStartTouch	!activator	kill		2.00	No

 

You can add as many outputs to the proxy as you would like (presumably), wiith as many entities as you'd like. This essentially turns the func_instance into a wildcard entity that borrows outputs from pre-configured entities, and lets the mapper choose how to use them.

Handling Inputs

The instance proxy can predefine important inputs when desired. This is useful for hinting to mappers what they can or should do with the instance, or by segmenting what can or can not be touched from outside the instance in order to avoid logical or behavioral errors.

To add a predefined input to the instance, go to the proxy's outputs tab and use the OnProxyRelay output to target one of the inputs of an entity inside your instance. It will look like this:

shaft_proxy - func_instance_io_proxy

	My Output >	Target Entity	Target Input	Parameter	Delay	Only Once
	OnProxyRelay	detect_stuff_trigger	disable		0.00	No

 

Once the proxy has the input specified, you'll be able to call it from enties outside the instance by targeting the func_instance...

elevator_arriving_relay - logic_relay

	My Output >	Target Entity	Target Input	Parameter	Delay	Only Once
	elevator_shaft_instance	instance:detect_stuff_trigger;Disable			0.00	No

 

The first thing you'll notice is that there's no need to fill in the target input field. You may also notice that Hammer didn't show this connection as working, but don't worry about it, for some reason Hammer still doesn't checklist these connections (it doesn't always use helpers, either).

You should refrain from predefining large numbers of inputs in the instance, and instead only do so for the standard functions of the instance. In other cases, you can still send messages to the instance entities directly by using their real name (e.g. elevator_shaft-detect_stuff_test). This is the method you would use for things that wouldn't be duplicated very often, or could be used to manipulate behavior in a more direct or abnormal way. In some cases you may need to use this method for calls that are too numerous or too basic to justify configuring the proxy. e.g. sections of a map being duplicated or rotated.

See also

• func_instance
• func_instance_parms - Entity to control parameters within instances.
• func_instance_origin - Helper entity that defines the center point of an instance.