Entity Lumps (SourceMod Scripting) - Revision history

Nosoop: Add notes on release and describe what the entity lump is

2023-10-09T05:03:44Z

Add notes on release and describe what the entity lump is

Nosoop: /* Entity Lump Entry */ Fixup code examples

2022-09-06T01:13:54Z

‎Entity Lump Entry: Fixup code examples

Nosoop: Add to scripting category

2022-09-06T01:10:46Z

Add to scripting category

Nosoop: Add initial page for entity lumps

2022-09-06T01:08:08Z

Add initial page for entity lumps

New page

Source Engine maps store entity data in [https://developer.valvesoftware.com/wiki/Source_BSP_File_Format#Entity the entity lump].

SourceMod implements functionality to manipulate this data in <tt>entitylump.inc</tt>.

=Introduction=

The global EntityLump methodmap contains functions to access individual entity entries. Below is an example lump that will be used throughout the rest of this page:

<pre>{
"world_maxs" "2624 4720 1728"
"world_mins" "-3536 -4720 -560"
"skyname" "sky_tf2_04"
"minoccluderarea_x360" "110"
"maxpropscreenwidth" "-1"
"detailvbsp" "detail_2fort.vbsp"
"detailmaterial" "detail/detailsprites_2fort"
"classname" "worldspawn"
"mapversion" "4067"
"hammerid" "4396"
}
{
"origin" "212.201 1784.53 259.256"
"fademindist" "-1"
"AutoMaterialize" "1"
"angles" "0 180 0"
"classname" "item_ammopack_small"
"hammerid" "5314720"
}
{
"origin" "-48 84 617"
"spawnflags" "1"
"classname" "logic_auto"
"hammerid" "741865"
"OnMapSpawn" "tonemap_global,SetAutoExposureMin,.8,0,-1"
"OnMapSpawn" "tonemap_global,SetAutoExposureMax,1.1,0,-1"
"OnMapSpawn" "tonemap_global,SetBloomScale,.5,0,-1"
"OnMapSpawn" "tf_gamerules,SetBlueTeamGoalString,#2fort_blue_setup_goal,0,-1"
"OnMapSpawn" "tf_gamerules,SetRedTeamGoalString,#2fort_red_setup_goal,0,-1"
"OnMapSpawn" "tf_gamerules,SetStalemateOnTimelimit,1,0,-1"
}</pre>

Plugins must modify the entity lump during the <tt>OnMapInit</tt> forward. Attempting to use non-read operations (such as update, insert, append, and erase) outside of that forward will raise a runtime error.

=Entity Lump=

The global <tt>EntityLump</tt> behaves like an {{SourceMod API|file=adt_array|function=ArrayList}}; to get a specific entity lump entry you must call its <tt>Get</tt> function:

<sourcepawn>
// get the worldspawn entity from the list
EntityLumpEntry entry = EntityLump.Get(0);

// release our handle to it when we are done
delete entry;
</sourcepawn>

If you don't know where your desired entity is, you must iterate over the list:

<sourcepawn>
for (int i, n = EntityLump.Length(); i < n; i++)
{
EntityLumpEntry entry = EntityLump.Get(i);
if (entry.FindKey("AutoMaterialize") != -1)
{
// this item has at least one 'AutoMaterialize' key
}
delete entry;
}
</sourcepawn>

=Entity Lump Entry=

<tt>EntityLumpEntry</tt> handles contains a list of key / value pairs.

You can modify an entry's values:

<sourcepawn>
// get the item_ammopack_small entity from the list
EntityLumpEntry entry = EntityLump.Get(1);

// find the 'classname' key in the list, then modify it
int icname = entry.FindKey("classname");
if (icname != -1)
{
// keep the name as 'classname', but change the value to 'item_ammopack_full'
entry.Update(icname, NULL_STRING, "item_ammopack_full");
}
</sourcepawn>

Keys do not have a one-to-one mapping with values; there may be duplicates. You can iterate over the available key / value pairs matching the key name with <tt>EntityLumpEntry.GetNextKey()</tt>:

<sourcepawn>
char outputString[256];
for (int i = -1; (i = entry.GetNextKey("OnMapSpawn", outputString, sizeof(outputString), i)) != -1;)
{
LogMessage("OnMapSpawn output: %s", outputString);
}
</sourcepawn>

← Older revision		Revision as of 01:10, 6 September 2022
Line 96:		Line 96:
	}		}
	</sourcepawn>		</sourcepawn>
		+
		+	[[Category:SourceMod Scripting]]

@@ Line 1: / Line 1: @@
-Source Engine maps store entity data in [https://developer.valvesoftware.com/wiki/Source_BSP_File_Format#Entity the entity lump].
+Source Engine maps store entity data in [https://developer.valvesoftware.com/wiki/Source_BSP_File_Format#Entity an entity lump], which is a plain text file containing a list of key / value pairs describing each entity.
-SourceMod implements functionality to manipulate this data in <tt>entitylump.inc</tt>.
+SourceMod implements functionality to manipulate this data in <tt>entitylump.inc</tt>.  This functionality was added to the development branch in 1.12.0.6922, then backported to the stable branch in 1.11.0.6919 (after its release).
 =Introduction=

@@ Line 85: / Line 85: @@
 	entry.Update(icname, NULL_STRING, "item_ammopack_full");
+}
 </sourcepawn>
@@ Line 90: / Line 91: @@
 <sourcepawn>
 char outputString[256];
 for (int i = -1; (i = entry.GetNextKey("OnMapSpawn", outputString, sizeof(outputString), i)) != -1;)
+{
 	LogMessage("OnMapSpawn output: %s", outputString);
+}
 </sourcepawn>
 [[Category:SourceMod Scripting]]