Post news RSS Custom Items

I talk a little bit about how custom items work in From Earth.

Posted by on

A bit of bad news. My PC kind of exploded, though I am bit a bit over dramatic when I say that. When I tried to turn it on I got light flash inside the case and another time I got sparks coming out from the back. Luckily, all my data is multiple times backed up so there's been no data loss. Only a bit of time lost since I have been spending the last week watching Netflix rather than doing any serious work. Can still do some work on my laptop, but I trying to calculate if I can afford to buy a new PC or not.

Meanwhile, here's some overly technical details about how custom items work in From Earth. Posting this to hear any comments or suggestions.

Item customization

When I say "custom item" or customizable I usually mean something that is not hard coded. A lot of the items with more complicated or specific functions in From Earth have hardcoded models and can't be changed by Level Designers without overriding the model completely. There's few classes, though, that allow the Level Designers to select the model for the item. Because of this, by "Custom Item" I mean items that can be either customized by myself, level designers, or later on possible modders of FE without needing additional programming.

Items such as Helmets and Goggles allow custom models, the modeller can define few values including: FOV when worn, color correction when worn, its armour value, if it protect the player from gas, and other special functions.

Melee weapons such as Swords and Sticks can have few settings defined: The Length, damage scale, speed, tip size, if it's meant to be used as a weapon, and what type of damage it does (slash or club).

All of this data is written in the $keyvalues section of the model .qc file. Goggles, Helmets, Swords, and Sticks all use a specific animation set that can't be changed by the modeller.


The "custom item" model called the "hlss_item" entity has more customization options, but they can't be used for specific functions, or as weapons, at least not yet. All of these settings need to be included in the "hlss_settings" suction. The hlss_item entity class is a multi purpose class, it's there not only to replace the default item class from HL2, but also to replace prop_physics to some extent.

First there's the animations set. Item / Weapon animations work differently in From Earth than in HL2. HL2 used activity tables specific for a weapon class, but instead of this I used one big table that defines all the basic activities (idle, walk, run, holster, deploy, drop, pickup, examine, etc.). The items refer to the animation set simply by its index in the table. In the keyvalues you simply refer to the name of the animation set and you don't have to worry about it knowing which animation to play. There's currently 21 unique animation sets.

"collisiongroup" Most items use the collision group "item". Items wont and shouldn't collide with the player or the NPCs as they can otherwise cause problems blocking the player from using interactive machines. If your item is really big, though, you can still make them collide with the player.

What is the market value of the item in the alien shops. Value from 0.05 to 1.

If the item can be scanned.

If the item can be disintegrated.

If the item can be created with vending machines.

How much damage does it do when and if it explodes.

Explosion radius. "merge_scale"
If the item is merged with another, how should we scale this prop to better fit.

You can define collisiontext for the model and make it breakable. Items that are breakable can't be created with vending machines.

Item ID refers to the system that allows the aliens to identify specific objects. This has very limited use in terms of custom items, as most item IDs are meant for hard coded items. Adding a new item ID would mean having to record a voice explanation for the item name by the three voice actors.

Only some animation sets have holstering animations, though I have been trying to add them to every set I can. The model needs to have an attachment defined where to put the item when it is holstered. Usually this has the same name as the animation set.


Shoes are also a subclass of "hlss_item". They can have more customization.

How fast or slow the shoes make you. Value from 0.5 to 1.5.

What bodygroup to use for Zenaida's legs (whether or not to hide part of them).

Shoes can increase or lower the damage you do when kicking.

Side-wall-running is disabled normally, but special shoes can re-enable it.

Limited ability to have a specific icon appear on the HUD. Doesn't really offer much help for modders.

The model to change to when the shoes are worn.

Custom Buttons

Items can have buttons defined for them. Right now it's not possible to define functions for custom items. Custom items can for example use the sword animation settings and have buttons that use the sword attack animation, but they wont do any damage since they don't have that built in them.

Adding an input output system would be problematic since if you disintegrate and then recreate that item, the input output data would be lost. Optionally if level designers had the inputs be dependent of entities other than the item themselves, it could create problems if the players would carry those items into another map. I am also not a fan of using the input output system excessively in general.

I have been thinking about adding a list of functions custom buttons could do, but I am not sure yet how it should work and what kind of list of functions I should add.

Buttons need to be defined in the "hlss_buttons" section.

Name of the attachment where to show the button when examining the item.

What type of button it is: "normal", "right", "left", "hold", "aim", "custom", "monitor", "knock", "open", "close", "invisible". Most of them only affect how they show up when examining the item, but "aim" and "hold" also change how they behave.

Kind of redundant and not required. Used to define a box around the attachment to help position the examine arrows.

The start activity for the button. Can be custom activity name.

The loop activity for the button. Not required.

The stop activity for the button. Not required.

If the button requires to have a specific prop model attached to the user to use this button. For example: You could define a lighter item that requires a cigarette model to be attached on the mouth for the player to use the lighter.

"item_prop" - "model"
Name of the model that needs to be attached. Modelnames like "models/items/cigarette01.mdl" and "models/items/cigarette02.mdl" are understood as the same model.

"item_prop" - "attachment"
Only accept models that are attached to this attachment.

"item_prop" - "effect"
Only accept models that have this effect enabled.

"item_prop" - "reverse"
Reverse the condition. For example, only allow the player to use the cigarette case if they don't already have a cigerette in their mouth.

"item_prop" - "search_operator"
If we should check the item or the operator for the item prop. By default yes.

"item_prop" - "required_for_npcs"
For example, the player can still open the cigarette case even if they have a cigerette, but an NPC should not open it if they already have one.

If the NPC should try to use this machine when they are bored. The NPC wont even go through the button requirements if this is set to false. By default this is disabled.

State the item needs to be in order for the player or NPC to use this button. For example, to take a cigerette, the cigarette case needs to be open.

Set the item into this state when this button is in its loop animation. For example, the player opens the cigarette case, starts playing the ACT_CIGARETTES_LOOP activity and can then use the button to take a cigerette.


You can define specific states for the item to be when it's used. This all need to be in the "hlss_states" section:

"next" Go to this state after finishing this one. By default goes back to not-working state.

How long to stay in this state. If zero stays in this state forever until another input.

"energy" Custom interactive machines can have required energy defined. Not yet implemented for items.

Which output to fire when the state is ended.

Loop this sound while the state is active.

Sound to play when this state is started.

Sound to play when this state ends.

Activity to play when the item starts this state. Is overriden by the player activity if the item has that activity.

Activity to play when the item loops this state. Is overriden by the player activity if the item has that activity.

Activity to play when the item stops this state. Is overriden by the player activity if the item has that activity.

Consider this the "default" state. Can be used to play sounds or such when no buttons are used.

Example Cigarette case

  "animations"  "holodisc"
  "collisiongroup" "item"
  "energy"  "1"
  "scanned"  "1"
  "disintegrated" "1"
  "holster"  "Holodisc"
  "bored_use" "1"

   "attachment" "Button"
   "type"  "normal"

   "state"  "open"
   "activity1"  "ACT_CIGARETTES_OPEN"
   "activity2"  "ACT_CIGARETTES_LOOP"
   "activity3"  "ACT_CIGARETTES_CLOSE"

   "attachment" "Cigarette"
   "type"  "normal"

   "required_state" "open"
   "activity1"  "ACT_CIGARETTES_SMOKE"

    "model" "models/items/cigarette01.mdl"
    "reverse" "1"
    "required_for_npc" "1"

   "attachment" "Cigarette"
   "type"  "invisible"
   "text"  "FE_DropCigarette"

   "activity1"  "ACT_CIGARETTES_DROP"

    "model" "models/items/cigarette01.mdl"
    "reverse" "0"

   "anim_loop"  "ACT_CIGARETTES_LOOP"
   "anim_stop"  "ACT_CIGARETTES_CLOSE"

Merging Items

Merging items or the "crafting system" is another thing I could talk about. It adds functionality to custom items, though even there the list of things you can do is finite. Just like the custom buttons in items, it's still stub, and wait for some kind of inspiration to see how I can improve it and add more. I will write a bit about the Item Merging later on.

Looking for help

We are still looking for people. If you are interested to apply, you can send me a message on Moddb, Twitter, Facebook, or e-mail me at

We are looking for a composer to help finish the music for From Earth.

We are interested on getting any help we can get, especially world texture creators and prop modellers.


So you can have multiple instances of that custom entity, with each having different properties? That's awesome!

Reply Good karma Bad karma+2 votes
Au-heppa Author

The properties are tied to the model. Usually in HL2 they would allow the level designer to define the properties, but I wanted to have consistency between levels. Not to mention the Hammer properties page would get bloated. Also, it's easier to make changes to model rather than having to apply the changes to all the levels and recompile them (even if you use instances).

Reply Good karma+1 vote

That is a great way! So each model has its properties, making it extremely easy to create new entities for mappers.

Reply Good karma Bad karma+2 votes
Post a comment
Sign in or join with:

Only registered members can share their thoughts. So come on! Join the community today (totally free - or sign in with your social account on the right) and join in the conversation.