Addoninfo.txt

From Valve Developer Community
Revision as of 14:25, 29 April 2023 by 結衣 (talk | contribs) (→‎Examples: Add minimally compliant AddonInfo)
Jump to navigation Jump to search

The plain-text file addoninfo.txt contains the KeyValues 1 structure AddonInfo specifying an addon’s metadata: its author, content flags, description, title, and version. This file and its functionality were introduced with the Left 4 Dead Left 4 Dead engine branch.

Both the Source Source Engine and the deprecated external application addoninstaller.exe will parse this file, though with significant differences. Source Source will parse this file from all addons listed in addonlist.txt when loading search paths from gameinfo.txt at startup and with subsequent calls to ConCommand update_addon_paths. Source Source will retrieve metadata for all Steam Workshop addons from the Steam Workshop, overriding content in addoninfo.txt. addoninstaller.exe only parses addoninfo.txt when staging addons during user-initialized installation.

Template:ModernWarning

Template:ModernWarning

Specification

In the following specification, these terms will have the following meanings:

  • shall indicates a mandatory requirement; and
  • should indicates a recommendation.

The Source Source Engine will expect a specific KeyValues 1 structure in addoninfo.txt, specified below:

  • You shall save addoninfo.txt with an UTF-8-compatible encoding.
  • You shall have at least one KeyValues block.
  • You should define the name of the first KeyValues block as AddonInfo.
  • You should populate the first KeyValues block with at least one key-value entry from table “Valid AddonInfo Keys”.
  • You should provide a title, author, and version.
  • You should provide at least one content tag.
  • You should preserve the case of each key.
Valid AddonInfo Keys
Key Type Length Default Value Description
addontitle wchar_t 127
  1. L4D360UI_Addon_None_Specified
 The addon’s title.
addonauthor wchar_t 119
  1. L4D360UI_Addon_None_Specified
 The addon’s author.
addonDescription wchar_t 1023
  1. L4D360UI_Addon_None_Specified
 The addon’s description. Left 4 Dead 2 Left 4 Dead 2 will truncate those of Steam Workshop addons to 499 characters [citation needed ].
addonversion wchar_t
float (addoninstaller.exe) 		31 0.0
1.0 (addoninstaller.exe) 		The addon’s version. Conventionally a decimal number in the format major.minor, but you may write any string.
addonContent_Campaign int N/A 0 If the addon contains custom campaigns. If the value is 0, then the addon does not contain the specified content; otherwise, the addon contains the specified content.
addonContent_Map int N/A 0 If the addon contains custom campaigns or custom maps.
addonContent_Skin int N/A 0 If the addon contains custom skins.
addonContent_weapon int N/A 0 If the addon contains custom weapon skins.
addonContent_BossInfected int N/A 0 If the addon contains custom boss infected skins.
addonContent_CommonInfected int N/A 0 If the addon contains custom common infected skins.
addonContent_Survivor int N/A 0 If the addon contains custom survivor skins.
addonContent_Sound int N/A 0 If the addon contains custom sounds.
addonContent_Music int N/A 0 If the addon contains custom music.
addonContent_Script int N/A 0 If the addon contains custom scripts.
addonContent_prop int N/A 0 If the addon contains custom props.

Non-existent or deprecated keys

Avoid writing these keys. All games ignore these keys. Valve provided these keys in the respective addoninfo.txt copies packaged with the example campaigns “DEADLINE” and “DEADLINE 2”.

Key Description
addonSteamAppID The AppID of the addon’s target game. Only addoninstaller.exe uses this.
addonTagline The addon’s subtitle or tagline. May have had a similar purpose to key poster/posterTagline in mission files.
addonAuthorSteamID The addon author’s SteamID. Supposedly used to construct a URL to the author’s Steam profile page.
addonSteamGroupName The addon’s Steam group. Supposedly used to construct a URL to the addon’s Steam group page.
addonURL0 The addon’s homepage. May have had a similar purpose to key Website in mission files.
addonContent_Survival
addonContent_Versus
addonContent_Scavenge 		If the addon provides custom campaigns supporting the Survival, Versus, or Scavenge game modes. This functionality is provided by mission files.
addonContent_Prefab If the addon provides custom Hammer Hammer prefabs.
addonContent_Spray If the addon provides custom logos.
addonContent_BackgroundMovie If the addon provides custom background movies.
Content_Weapon If the addon provides custom weapons (e.g., “…a new weapon, i.e. guns, explosives, booby traps, hot tar, etc.”).
Content_WeaponModel If the addon provides custom weapon model.
addonDescription_locale The addon’s description localized for locale locale, where locale is an ISO 639-1 code in ALL CAPS.

Content tag handling

An addon’s AddonInfo content keys provide an abstraction over Source Source’s implementation-specific content tags. Source Source will convert all keys into an internal representation (typically, a bitfield). A content key may correspond to its internal tag; some keys provide redundant meaning useful only to authors and distributors. Source Source will use these content tags to describe and filter addons in the CBaseModFrame Addons.

Template:ModernBug

In Left 4 Dead Left 4 Dead and Alien Swarm Alien Swarm

Left 4 Dead Left 4 Dead maintains a one-to-one correspondance between content keys and content tags. The handler closely resembles that found in the Alien Swarm Alien Swarm SDK.

Source Source will generate the content label by concatenating the VGUI localization strings corresponding to the given content tag followed into an array of 60 wide characters. The right-most comma will always be replaced with a NULL terminator. The effective length of the label is 59 characters since the last character will always be a NULL terminator.

In Left 4 Dead 2 Left 4 Dead 2

Left 4 Dead 2 Left 4 Dead 2 stores the content keys for each addon as an int16_t representing the following bitfield (assume little-endian):

Left 4 Dead 2 Left 4 Dead 2 content tag bitfield
Bit 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
Tag N/A N/A N/A N/A CONTENT_ITEM CONTENT_UI CONTENT_SCRIPT CONTENT_SOUND CONTENT_SURVIVOR CONTENT_INFECTED CONTENT_MUTATION CONTENT_WEAPON CONTENT_SKIN CONTENT_MISCELLANEOUS CONTENT_CAMPAIGN CONTENT_RESERVED
Key N/A N/A N/A N/A addonContent_prop N/A addonContent_Script addonContent_Sound
addonContent_Music 		addonContent_Survivor addonContent_BossInfected
addonContent_CommonInfected 		N/A addonContent_Weapon addonContent_Skin N/A addonContent_Campaign
addonContent_Map 		N/A

The content tags CONTENT_MISCELLANEOUS, CONTENT_MUTATION, and CONTENT_UI can be set only through the Steam Workshop.

Source Source will generate the content label by concatenating the VGUI localization strings corresponding to the given content tag followed into an array of 60 wide characters. The right-most comma will always be replaced with a NULL terminator. The effective length of the label is 59 characters since the last character will always be a NULL terminator.

Examples

The following are samples—both modern and historic—of addoninfo.txt. Avoid using the “DEADLINE” or “DEADLINE 2” samples as templates: you will be shipping redundant keys.

Minimally compliant AddonInfo

Template:ModernWarning 

{}

Generic compliant AddonInfo

AddonInfo {
	addontitle			"こんにちは、世界！"	// Title is interpreted as a UTF8 string;
												// prefer codepoints in the Basic
												// Multilingual Plane.
	addonauthor			ValveDeveloperWiki
	addonversion		something				// This can be anything and not just a float
	addonDescription	"This is a sample.

Note that the KeyValues parser will, in a quoted string, a) parse all
whitespace literally and b) // ignore all C-style comments. You could
probably use this to validate a KeyValues parser too.
"
	addonContent_Campaign	1
	addonContent_Survivor	-1
	addonContent_Sound		3.14159265
}

“DEADLINE”

Download Valve’s “DEADLINE” campaign from here. The following snippet matches the original exactly as of April 30, 2023. 

// The addoninfo.txt file is a metadata file that is required by all Left 4 Dead Add-ons. 


"AddonInfo"
{
        addontitle		"Dead Line"                                     // Add-on title that shows up in Add-ons list. ~20 chars max
        addonversion	        1.3                                             // Add-on version.
        addontagline		"Catch the last subway... out of hell."	        // Add-on tagline or wrap-up- a short description. ~100 chars max
	addonauthor 		"Valve"                                         // Name/alias of the author
	addonauthorSteamID 	"http://steamcommunity.com/groups/Valve"        // Steam Profile URL of author or group

	addonContent_Campaign		1 	                                //This addon provides muliple connected maps with a finale

	addonURL0 "http://media.steampowered.com/apps/513/deadline.html"	//An html home page for the add-on that includes a download link.

	// short description that appears in the Add-on list screen...
	addonDescription "Survivors must escape on a subway train in this short tutorial example campaign. Get source files and tools for creating your own campaigns by downloading the Left 4 Dead Authoring tools SDK, which is available under the 'Tools' tab in Steam."
	
	// Authors can add localized descriptions here. (Not yet supported)
	addonDescription_FR "Les survivants doivent s'échapper en métro dans cette carte du tutoriel. Obtenez les fichiers et les outils pour créer vos propres cartes en chargeant les outils de création SDK Left 4 Dead qui sont disponibles sous l'onglet "Outils" sur Steam."	

}

“DEADLINE 2”

Download Valve’s “DEADLINE 2” campaign from here. The following snippet matches the original exactly as of April 30, 2023. 

// The addoninfo.txt file is a metadata file that is required by all Source Engine Add-ons.

"AddonInfo"
{
     addonSteamAppID         550                                                     // 500 is the app ID for Left 4 Dead, 550 for Left 4 Dead 2
     addontitle              "Dead Line 2"                                           // Add-on title that shows up in Add-ons list. ~20 chars max
     addonversion	     1.0                                                     // Add-on version.
     addontagline            "Catch the last subway... out of hell... Again!"	     // Add-on tagline or wrap-up- a short description. ~100 chars max
     addonauthor             "Valve"                                                 // Name/alias of the author
     addonSteamGroupName     "deadline2add-on"                                       // (Optional) Steam group related to the add-on. We use this to construct a URL to the group page.
     addonauthorSteamID      "YasserMalaika"                                         // (Optional) Steam ID of author. We use this to construct a URL to the author's page.
     addonContent_Campaign   1 	                                                     //This addon provides muliple connected maps with a finale
     addonURL0               "http://media.steampowered.com/apps/513/deadline2.html" //An html home page for the add-on that includes a download link.

     // short description that appears in the Add-on list screen...
     addonDescription        "Survivors must escape on a subway train in this short tutorial example campaign. Get source files and tools for creating your own campaigns by downloading the Left 4 Dead 2 Authoring tools SDK, which is available under the 'Tools' tab in Steam."

     // Authors can add localized descriptions here. (Not yet supported)
     addonDescription_FR     "Les survivants doivent s'échapper en métro dans cette carte du tutoriel. Obtenez les fichiers et les outils pour créer vos propres cartes en chargeant les outils de création SDK Left 4 Dead 2 qui sont disponibles sous l'onglet "Outils" sur Steam."	
 
}

See also

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Addoninfo.txt&oldid=302068"