CSTNet 2.1.200
dotnet add package CSTNet --version 2.1.200
NuGet\Install-Package CSTNet -Version 2.1.200
<PackageReference Include="CSTNet" Version="2.1.200" />
<PackageVersion Include="CSTNet" Version="2.1.200" />
<PackageReference Include="CSTNet" />
paket add CSTNet --version 2.1.200
#r "nuget: CSTNet, 2.1.200"
#:package CSTNet@2.1.200
#addin nuget:?package=CSTNet&version=2.1.200
#tool nuget:?package=CSTNet&version=2.1.200
🔠 CST.NET
CST.NET is a .NET library for parsing Maxis' key-value pair format. It can be used with custom frameworks or the original UIText APIs.
What is CST?
Caret-Separated Text (or CST) is a string-text format: a plain-text resource format with digits or words as keys and each value enclosed between carets. (e.g. <key> ^<value>^) Maxis used it as early as Sims Steering Committee, a prototype of The Sims, for animation, file, and texture names, and later in The Sims Online for its interface text. It's handy on its own for any project that wants a simple table of strings or a clear path to translation.
Features
- TSO compatible, checked against the beta, base game, and New & Improved
- Values with no key, and names above values
- Keys with spaces, and indented keys
- Variables
- UTF-8 and Windows-1252 files
- References between tables
- Sims Steering Committee compatible
- Numbered keys such as
1.labeland1: -
.dirfolders of#<id>#<name>.csttables, laid over one another
- Numbered keys such as
- Multiline values
- C-style comments
- Malformed entries reported rather than stopping the read
- UIText
The format is described in the CST specification.
Installation
dotnet add package CSTNet
Usage
using CSTNet;
var table = CSTTable.Parse("1 ^Hello, %s!^\nok button ^Accept^");
if (table.TryGetValue("1", out var hello))
Console.WriteLine(CST.Format(hello, "World")); // Hello, World!
Console.WriteLine(table.Entries.Count); // Every value, in file order
Console.WriteLine(table.Problems.Count); // Anything malformed
TryGetValue returns false for a missing key, so it can't be mistaken for real text. A key must match whole, so ok doesn't find ok button. Values come back as written, and CST.Format fills placeholders such as %s and %03d in order.
For a one-off lookup, CST.Parse returns the value, or ***MISSING*** for a missing key:
var accept = CST.Parse(content, "ok button");
UIText
UIText looks up a key in a table named _<id>_<name>.cst, the way The Sims Online does. Pass an install's gamedata directory, and it finds the layout itself, whether New & Improved's uitext/<language>.dir or the earlier uitext.dir. It reads UTF-8 and Windows-1252 files, finds values with no key by their position from 0, and follows references between tables.
var text = new UIText("english", "/path/to/TSOClient/gamedata");
if (text.GetTextIfPresent(154, 1) is { } greeting)
Console.WriteLine(greeting);
GetTextIfPresent returns null for a missing table or key, while GetText returns ***MISSING***. Filesystem errors are thrown to the caller. Each lookup reads the table again, so for many lookups in one table, use CSTTable.
Folders and layers
For a game's own tables kept directly in a folder, such as Sims Steering Committee's .dir folders, CSTDirectory reads every #<id>#<name>.cst or _<id>_<name>.cst table at once. CSTLayers looks through several directories in order, such as a person's tables over the global ones:
var layers = new CSTLayers(CSTDirectory.Read(rossPath), CSTDirectory.Read(globalPath));
if (layers.TryGetValueAt(130, 20, out var animation, treatEmptyAsMissing: true))
Console.WriteLine(animation); // Ross's slot is empty, so this is the global table's value
See the usage guide for how keys are found, problems, UIText's limits, and layers, and the changelog for what changed in each release.
Supported Versions
| CSTNet | Minimum .NET Version |
|---|---|
2.1.200 ... |
.NET 10 |
2.0.100 ... 2.0.103 |
.NET 6 or .NET Standard 2.1 |
Background
This all began as a "what if?" What if I could made my own CST parser? It was an attempt to create my first algorithm. One that was a little better than came before. So, I did. First from a Jupyter notebook and then a full-fledged project that's taken on a life of it's own!
License
I license this project under BSD-3-Clause license — see the LICENSE file for full text.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 2.1.200 | 54 | 11/19/2026 |
| 2.1.200-alpha | 46 | 11/19/2026 |
| 2.0.103 | 384 | 8/10/2023 |
| 1.0.300 | 745 | 12/13/2020 |