Module tutorial: stringtables

[your-name-here]

I've recently found some free time and I've been helping the Source.Python team document their code. This post will be focused on the stringtables module. I'm hoping that posting this content here will make it more visible than just posting it on the wiki.

Introduction:
Understanding what string tables are and what they're used for is fundamental to knowing how to interface with them in Source.Python. It's pretty simple: A string table is a named collection of entries. Each entry is associated with three pieces of information:

• An index which is used by the engine to look up an entry.
• A key which serves as the name of the entry.
• A value which is the data the entry maps to. This is referred to as user data.

String tables are shared between the client and the server. If you've ever worked with downloadables in either Eventscripts or Source.Python, you will have experienced this. There are numerous string tables built into the Source engine. Different engines have different string tables. Each string table has a different purpose.

Using stringtables:
Now that we've covered what stringtables are, let's talk about how you can use Source.Python to interface with them. Keep the stringtables documentation page open as you read through this post. All of the methods used in the code snippets are documented on that page.

There are two major constructs Source uses for string tables:

• INetworkStringTableContainer - This is the main interface into the string table system. As the name says, it provides access to the overall collection of string tables. The Source.Python equivalent is string_tables. This is the singleton you will need to use in order to access string tables.
• INetworkStringTable - The actual string table class. The Source.Python equivalent is StringTable.

The most common use of string tables are to make custom server assets downloadable by a client. The stringtables package does have a downloads module within it. You can use this to add your own models/assets to the download table in order to allow clients to grab custom content. In the interest of exploring stringtables, I will ignore this module until the very end of this post.

The first step is to actually acquire a StringTable instance of the string table you want to modify. You'll need to use string_tables in order to accomplish this. There are multiple methods that you can use to achieve this:

Syntax: Select all

# ======================================================
# >> IMPORTS
# ======================================================
# Source.Python
from stringtables import string_tables

# By direct access.
downloadables = string_tables.downloadables
print('1. ' + downloadables.name)

# By name.
downloadables = string_tables['downloadables']
print('2. ' + downloadables.name)

# By index.
downloadables = string_tables[0]
print('3. ' + downloadables.name)

Now that we've got a StringTable instance, we can perform a few operations on it:

Syntax: Select all

# ======================================================
# >> IMPORTS
# ======================================================
# Source.Python
from stringtables import string_tables

# Retrieve the downloadables table.
downloadables = string_tables['downloadables']

# Print out it's name.
print('Name: %s' % downloadables.name)

# Print out the index of the table in string_tables.
print('Index: %d' % downloadables.index)

# Print out the number of current entries in the table.
print('Entry count: %d' % len(downloadables))

# Print out the maximum number of allowed entries in the table.
print('Maximum entries: %d' % downloadables.max_strings)

Code: Select all

Name: downloadables
Index: 0
Entry count: 39
Maximum entries: 8192

You can treat a StringTable instance just like a list. The subscript you use is the entry within the table that you want to access. The following python script prints out the first five entries in the downloadables table:

Syntax: Select all

# ======================================================
# >> IMPORTS
# ======================================================
# Source.Python
from stringtables import string_tables

# Retrieve the downloadables table.
downloadables = string_tables['downloadables']

# Print out the first five entries.
for i in range(0, 5):
    print('downloadables[%d]: %s' % (i, downloadables[i]))

And the result:

Code: Select all

downloadables[0]: maps/ar_shoots.bsp
downloadables[1]: maps/ar_shoots.nav
downloadables[2]: models/weapons/w_c4_planted.mdl
downloadables[3]: models/player/tm_pirate.mdl
downloadables[4]: models/player/tm_pirate_variantA.mdl

The printed string is actually the name of the entry in the table. For the downloadables table, the value is actually the same as the key. This makes it very simple to add something to the downloadables table:

Syntax: Select all

# ======================================================
# >> IMPORTS
# ======================================================
# Source.Python
from stringtables import string_tables

# Retrieve the downloadables table.
downloadables = string_tables['downloadables']

# Add some custom model to the table.
modelname = 'guns/my_custom_gun.mdl'
modelname_index = downloadables.add_string(modelname, modelname)

# Print out the index the string was added at.
print(modelname_index)

# Print out the entry name.
print(downloadables[modelname_index])

And the output:

Code: Select all

39
guns/my_custom_gun.mdl

Your downloadable is now added to the table :)