Wire Map Interface - wiremod/wire GitHub Wiki

About

The WMI is a bridge between the map and Wiremod, it is an entity (info_wiremapinterface) that is able to give other entities wire ports. E2 wirelinks are supported. Highspeed or memory wire ports are not supported. E2 wirelinks only work when actually wired, not when using E:wirelink()

This point entity is made for the use in the Valve Hammer Editor and is invisible in-game. It supports all popular data types and it is easy to use. It is shipped with Wiremod.

If Wiremod is not installed, the entity will be not loaded, there will be a message in the console that info_wiremapinterface was not found and that it will be ignored. The map will run just fine, beside that you can't use the wire ports of course.

What you have to know

If you want to use this entity you should know this:

  • How to use Wiremod.
  • How to use the Input/Output system of the editor.
  • How to add entities to the map and how to set them up.
  • What *.fgd-files are and how to install/use them.
  • How to make and compile a functional map.

For server admins

Prop protection and controlling

You can control the use of the WMI by disabling or enabling it using the ConVar below. If you want a per player controlling, you will have to use a prop protection addon.

ConVars

  • sv_wire_mapinterface 1/0 - Enable or disable all Wire Map Interface entities. Default: 1
  • sv_wire_mapinterface_min_trigger_time 0-1 - Sets minimum time between Wiremod input triggers per Wire Map Interface entity and Wiremod input. Default: 0.01
  • sv_wire_mapinterface_max_sub_entities 1-128 - Sets maximum count of sub entities per Wire Map Interface entity that can get wire ports. Default: 32

For mappers

The *.fgd-file

Before you can use the WMI in the Hammer Editor you have to load the file wiremod.fgd in the editor. You can find it the root folder of your copy of Wiremod. If you can't find it then you can use this.

The entity properties

If your editor successfully loaded the *.fgd-file and you should be able create a info_wiremapinterface entity easily. If you open its properties menu then you should see this:

Entity properties

This following table explains the key names: (<N> is the number).

Property Name Key Name Description Type Default Value
Name targetname The name of the interface entity. String (entity name) <none>
Wire Entity wire_entity_name The interface gives up to 32 entities with this targetname wire ports. String (entity name) <none>
Minimum Trigger Time min_trigger_time The minimum time in seconds between two in-/output triggers. It's useful to prevent lags. Floating Number 0.01
Wire Input <N> Name input<N>_name The name of the Nth input. String <none>
Wire Input <N> Type input<N>_type The type of the Nth input. See data type section! int number (choices) 0 (Normal)
Wire Input <N> Description input<N>_desc The description of the Nth input. It's shown behind the input name in-game. String <none>
Wire Output <N> Name output<N>_name The name of the Nth output. String <none>
Wire Output <N> Type output<N>_type The type of the Nth output. See data type section! int number (choices) 0 (Normal)
Wire Output <N> Description output<N>_desc The description of the Nth output. It's shown behind the output name in-game. String <none>

The Hammer outputs

Setting of names and types of entities and ports alone will not work. You have to also connect the interface's Hammer outputs to other entities. What Hammer inputs you connect them is your choice. In this screenshot I connected them to a door:

Entity outputs

Valid outputs are: (<N> is the number):

Name Description Type
OnResetWireInput<N> Fired when the Nth wire input got reset. Useful if you have something that isn't zero by default. Void
OnWireInput<N> Fired when the Nth wire input got triggered. Leave the override parameter empty, if you want to use the input value! String
OnWireEntsCreated Fires when Wire In-/Outputs entities have been created. The entity is ready to use. Void
OnWireEntsRemoved Fires when Wire In-/Outputs entities have been removed. The entity is ready to use. Void
OnWireEntsReady Fires when Wire In-/Outputs entities have been created or removed. The entity is ready to use. Void
OnWireEntsStartChanging Fires when the wire map interface entity is adding or removing Wire In-/Outputs entities. The entity can't be used yet. Void

The Hammer inputs

Of course this entity has also Hammer inputs, they are useful if you want to build a wire-input-entity-dispenser or if you want to make a kind of a puzzle map for instance.

Valid inputs are: (<N> is the number):

Name Description Type
TriggerWireOutput<N> Sets the Nth wire output to the given var when trigged. String
AddEntity Gives the wire ports to calling entity. Void
RemoveEntity Remove the wire ports from the calling entity. Void
AddEntities Adds entities by name that will get wire ports. String (entity name)
RemoveEntities Remove the wire ports from the named entities. String (entity name)
RemoveAllEntities Remove the wire ports from all entities. Void
Activate Allow the triggering from wire inputs and the updating of wire outputs. Void
Deactivate Disallow the triggering from wire inputs and the updating of wire outputs. Void
Toggle Toggle the above status. Void

The spawnflags

I think this screenshot should explain enough. These are for built-in entity protecting, removal behavior and wire rendering

Entity spawnflags

Connectivity with lua_run entities.

The WMI can trigger lua_run entities. Its Lua code will know about the WMI globals when it was triggered by info_wiremapinterface entities. These globals are listed below:

Variable Description Type
WIRE_NAME Input name String
WIRE_TYPE Input type (NORMAL, STRING, VECTOR, etc.) String
WIRE_VALUE Input value <varying>
WIRE_WIRED Is the input wired? Boolean
WIRE_CALLER This interface entity Entity
WIRE_ACTIVATOR The entity that has the Wire input Entity
WIRE_DEVICE The entity where the input data was from, e.g. a Wiremod button Entity
WIRE_OWNER The owner of the input device, e.g the player who spawned the Wiremod button Entity

This table shows some Lua methods of the interface:

Name Takes Returns Description
Entity:AddEntitiesByName String <Nothing> Adds entities with the given name to the list and give them wire ports.
Entity:AddEntitiesByTable Table <Nothing> Adds entities in given table to the list and give them wire ports.
Entity:RemoveAllEntities <Nothing> <Nothing> Removes the wire ports from all the interface's entities.
Entity:RemoveEntitiesByName String <Nothing> Removes the wire ports from the interface's entities that has the given name.
Entity:RemoveEntitiesByTable Table <Nothing> Removes the wire ports from the interface's entities that has the given table.
Entity:GetWiredEntities <Nothing> Table Returns a table of all interface's wire ports entities.
Entity:SetWiredEntities Table <Nothing> Removes the wire ports from all the interface's entities and then adds wire ports to all entities in the given table.

Security rules

To prevent any nasty stuff from happening, such as players running arbitrarily server side lua code, you must follow these rules when designing maps:

  • Never pass user input as Lua code!
  • Never use RunString or CompileString on user input! The best is to never use those at all in lua_run entities.
  • Never add Hammer I/O (AddOutput) from user input!
  • Never attempt to override/bypass any protection logic that might disable lua_run or info_wiremapinterface entities. Expect it to happen on some servers and design fallbacks into your map accordingly.

The WMI will block setups that would run Lua code or add Hammer I/O from user input. When attepted a warning message will be printed and the Hammer I/O will be deleted in game.

Warning: Attepting to bypass that protection is concerned as malicious map design. You have been warned!

Blocked input warning

Old input code

To prevent abuse, the Wire Map Interface can no long supports running lua from Wire Input <N> Code / input<N>_lua fields. These field have been removed. Attempting to use them will print a warning message.

To migrate from old map logic, you can just copy paste the used lua code into a lua_run entity and trigger it.

Important limits of using lua_run entities

Warning: Be very careful when you put Lua code a lua_run entity. There is a limit of 512 chars for the code and you have to avoid double quotation marks (") and replace them with single quotation marks ('). There is no way around, it's a problem of the Hammer editor! Carelessness may corrupt the map!

Supported data types

The WMI supports all common data types. This is a table of all supported data types and how they are converted:

ID Wire Data Type Lua Data Type How it is converted to wire output? How it is converted to wire input?
0 NORMAL Number Number from String. Number to String.
1 NORMAL (Toggle) Number (0 or 1) Toggling between 0 and 1 each time it is triggered. It triggers the input only when value is above 0. (Useful inputs for wired buttons.)
2 STRING String String is string String is string
3 VECTOR2 Table with 2 indexes Get the first 2 numbers separated by spaces from a string. Get the 2 values and put them separated by spaces in to a string.
4 VECTOR Vector Get the first 3 numbers separated by spaces from a string. Get the 3 values and put them separated by spaces in to a string.
5 VECTOR4 Table with 4 indexes Get the first 4 numbers separated by spaces from a string. Get the 4 values and put them separated by spaces in to a string.
6 ANGLE Angle Get the first 3 numbers separated by spaces from a string. Get the 3 values and put them separated by spaces in to a string.
7 ENTITY Entity Get them by targetname or by ID number Get ID number from the Entity
8 ARRAY Table Spit string values are separated by spaces. Put values into a string and separate them by spaces.

Supported special targetnames.

When specifying a targetname in Hammer I/O you may also use special targetnames starting with an exclamation mark (!) to find target entities dynamically.

Side Note: Classnames instead of targetnames are supported too.

Targetname Hammer input Hammer output
!null Nothing, no entity same as input
!self The Wire Map Interface entity same as input
!player All players same as input
!caller The entity calling the input, e.g. a trigger brush same as !self
!activator The entity triggering !caller, e.g. a player/npc touching the trigger brush The map entity a wire signal was triggered in to, e.g a wired key pad of a door
!input same as !activator output same as input
!device The entity where the input data was from, e.g. a Wiremod button same as input
!owner The owner of !device, e.g. the player who spawned the Wiremod button same as input

This screenshots shows an example of a trigger brush passing player/NPC as an entity to use in Wiremod. Note as it uses !null to reset the entity output to null again, because passing an empty string will not always be applicable.

Inputs with special targetnames

The example map

This is the official example map, so you can take it apart to see how it is used.

You don't have to ask for any permissions, you can always use parts or everything of the example map for everything you want. The *.vmf source file is included.

You have full permission to use, modify and release/reupload the map, its source or any part of it when ever you like.

Downloads

Happy mapping and wiring!

⚠️ **GitHub.com Fallback** ⚠️