Applying Custom Attributes - nosoop/SM-TFCustAttr GitHub Wiki

After installing (or creating) some custom attribute plugins, you'll probably want to get them applied to a weapon. There are a number of options available.

Prerequisites

The core plugin, tf_custom_attributes.smx, must be installed. That is available from this project's releases page.

At the moment, the plugin depends on TF2Attributes. The original version by FlaminSarge is acceptable, though my fork provides additional features that custom attribute plugins may depend on.

If you're using it with one of the Custom Weapons plugins, it's assumed it's already installed and configured correctly.

With the basic Custom Attribute Manager

The attribute manager applies custom attributes from a section of a KeyValues configuration file based on item definition index. It's mostly intended as a demonstration of the API for other future equipment-managing plugins.

  1. Install tf_custom_attributes_manager.smx from this project's releases page.
  2. Add a section in configs/tf_custom_attributes.txt with the item definition index you want to add custom attributes to. An example copy of the configuration is available in the repo, linked here.
  3. Add the attribute name and value.
  4. Reload the manager using the tf2custattrman_reload command and re-equip any weapons that have changed (change class and back again).

With the Custom Attribute Debugger

The custom attribute debugger is a utility that allows administrative users to apply attributes to their current weapon and to see all attributes present on their player. It's intended for quick development purposes.

  1. Install tf_custom_attributes_debugger.smx from this project's releases page.
    • You may also want to install tf2wearables to see attributes on non-weapon equipment.
  2. While in-game, use the command sm_custattr_add [attribute] [value] to apply the given attribute name and value to your currently equipped weapon. You can use the command sm_custattr_show to get a list of attributes on yourself and your equipment.

With Custom Weapons 2 / Custom Weapons 3

All versions of Custom Weapons is supported through an 'adapter' plugin, which acts as a CW2/3 attribute plugin whose only purpose is to forward the attribute applied event from Custom Weapons to an "add attribute" native call on Custom Attributes's side.

For Custom Weapons 3, both cw2attributes.smx and cw3-attributes.smx should be installed.

It's recommended that you do not put any Custom Attribute files (whether core or attribute plugins) under cw3/ or customweaponstf/. These plugins are their own framework and do not follow any of the Custom Weapons' plugin conventions.

  1. Install custom_weapons_adapter.smx from this project's releases page (the attribute plugins can be located anywhere).
  2. In your custom weapon config (configs/customweaponstf/*), create a section for the attribute name as with any other attributes.
    • You can place it under attributes or cw3_attributes; the adapter responds to both. That said, there may be a few quirks specifically with CW3 due to the forward using weapon slots instead of passing the weapon entity directly — the adapter will warn you of such instances in the server console.
  3. Set the plugin value in your newly created attribute subsection to either start with custom-attribute-adapter or custom-attribute-adapter/${PLUGIN_NAME}.
    • The adapter only processes attributes starting with custom-attribute-adapter.
    • If the second format is used, ${PLUGIN_NAME} must be the base name (no folders, no extension) of a loaded plugin for the adapter to process it.
      • This allows CW2/CW3 to report better diagnostics to ensure the attribute plugin is installed correctly, as custom attributes don't do any sort of self-registration.
      • Unlike CW-based attributes, this does not allow different custom attribute plugins to use the same attribute name; attribute names that are equal will point to the same value.
    • Note that CW2/CW3 truncates attribute and plugin names to 63 characters (excluding null terminator). Attribute values are truncated to 319.
  4. Reload Custom Weapons with sm_c reload and equip your weapon.

With Custom Weapons 4

CW4 isn't publicly available. However, it's being used with Custom Attributes, so instructions are provided for reference.

As with CW2/3, do not install attribute plugins under cw3/ or customweaponstf/.

  1. Install custom_weapons_adapter.smx from this project's releases page as plugins/customweaponstf/custom-attribute-adapter.smx. Yes; you'll need to rename it, and it must be in that location.
  2. Create custom-attribute-adapter.cfg in plugins/customweaponstf/. This is a new requirement in CW4.
    • Declare the attribute definitions for the custom attributes here.
  3. Set only custom-attribute-adapter as the plugin name in your weapon config. Otherwise, the attribute is declared similar to CW2 and CW3 (starting from step 2 in those instructions).
  4. Reload Custom Weapons with sm_c reload and equip your weapon.

With Custom Weapons X

Custom Weapons X has first-class support for the Custom Attributes framework. Probably because I wrote both, but whatever.

Add your Custom Attributes under an item's attributes_custom subsection in the same format as the Custom Attribute Manager; keys and values correspond to attribute names and values respectively.

With Freak Fortress 2

NoloZero01 has created an adapter that integrates custom attributes with Freak Fortress. Check out the linked thread for the latest setup instructions.

The integration provides a new customattributes section for boss weapons to use.

Troubleshooting

I can't find the compiled .smx files, only .sp.

In most cases, I provide precompiled plugins in the releases section. For other repositories, the link to that section is right above the file listing on the main repository view.

An error "Could not find required attribute plugin ${filename}" shows up in console when I try to equip a weapon with one of these attributes.

The weapon config requests a plugin ${filename} that isn't loaded in. Assuming you definitely have that plugin installed, check sm plugins list and unload / load the plugin to see what error is causing it to not load.

An error "Exception reported: Invalid Handle 0" is reported when trying to load a plugin on Windows. Topmost entry in the stack trace is DHookEnableDetour.

Due to the byte-based signature lookup on Windows, multiple plugins cannot detour the same function without masking out the first six bytes. Remove other plugins that hook the same function for now. File an issue with the specific attributes and detour causing issues. If it's conflicting with a plugin by another author, you will also need to contact them to mask out the same bytes.