Skip to content

Library Reference

The native interface is currently subject to change.

We're in the process of rewriting and unifying the interface for the different flavors of pre-built shared libraries. As such the following information might change slightly.

Most projects implement our Grammar Engine by linking to it as a shared library or embedding its code directly in the target project. This C interface may be used with any native or managed program being capable of calling it properly. Using the source code version is very similar, although there are alternative signatures available (such as passing std::wstring rather than wchar_t or working with buffers directly).

Our interface files for Microsoft's .NET Framework – Grammar.cs and NativeMethods.cs expose the same interface directly to your managed code.

Overall, the interface is kept in a minimalistic and intuitive way to make it easier to learn and use effectively.

Encoding Difference

It's important to note that Mono (as used by Unity Engine and other projects) always passes strings as 16 bit wide characters rather than following whatever size wchar_t for the current system is. As such a regular shared library build will expect strings consisting of wchar_t, while a plugin library build will expect char16_t.

The following section will use the pseudo type string rather than naming types explicitly.

Specific Type Information

Please refer to your actual header or interface files for the appropriate type to pass or expect as these might change slightly based on the language you're using in your project.


void initialize();

Initialize the Grammar Engine. This mandatory call has to be performaed once before using any other function in the library. This runs necessary one-time setup routines, ensures the library is properly loaded, and verifies the validity of the license. This happens offline and won't contact any web service or the like.

It's not necessary to call this function when using our interface files for the .NET Framework.


bool isAvailable();

Retrieves the status of the library. If there's been some issue or the license for the trial version expired, this will return false. Otherwise the result will be true.


void setLanguage(string lc);

Switches the Grammar Engine's active language based on the 2 letter language code being provided. The valid values depend on your license or trial version. Invalid or unsupported language codes will result in a fallback to the English (en) version, which is always available.

Retrieve Supported Languages

To retrieve a comma separated list of the supported languages, you can use the built-in constant grammar::languages, e.g. by passing "<<grammar::languages>>" to useGrammar().


string getLanguage();

Returns the currently selected language as a 2 letter language code.


string useGrammar(string text, string params[], int param_count);

Applies all param_count parameters inside params to the text template string and returns the formatted result. Passed parameters are assigned to numbered variables starting at 1.

Freeing Resources

If this function is called directly, the calling process is responsible for freeing the returned string's allocated memory using CoTaskMemFree() (Windows) or free() (others).


string generateName(string noun, string affixes[], int affix_count);

Attaches all affix_count affixes inside affixes to the noun base word and returns the combined, tagged result.

Freeing Resources

If this function is called directly, the calling process is responsible for freeing the returned string's allocated memory using CoTaskMemFree() (Windows) or free() (others).


void setVariable(string name, string value);

Assigns value to the global variable name. Keep in mind that name must be alphanumeric and start with a letter. Reassigning a variable will overwrite the previous value.

Global Variable Usage

Global named variables are perfect for values that seldomly change but might be useful for content creators and translators alike. Perfect examples would be the current player's name, the player's active target, their race, etc.


void clearVariable(string name);

Deletes the global variable name. This has no effect, if the variable hasn't been set yet.


void clearVariables();

Deletes all global variables. This has no effect, if there aren't any custom variables set.

Last update: April 20, 2020