CSTNet 2.1.200

dotnet add package CSTNet --version 2.1.200
                    
NuGet\Install-Package CSTNet -Version 2.1.200
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CSTNet" Version="2.1.200" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="CSTNet" Version="2.1.200" />
                    
Directory.Packages.props
<PackageReference Include="CSTNet" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add CSTNet --version 2.1.200
                    
#r "nuget: CSTNet, 2.1.200"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package CSTNet@2.1.200
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=CSTNet&version=2.1.200
                    
Install as a Cake Addin
#tool nuget:?package=CSTNet&version=2.1.200
                    
Install as a Cake Tool

🔠 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.label and 1:
    • .dir folders of #<id>#<name>.cst tables, laid over one another
  • 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • 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