Tokens, events and help

The examples use the GameChat engine and Player source from The chat engine.

Token replacements

RegisterStringReplacement replaces a token in every line before the engine reads it, commands included:

using BSGameLib.Chat;

var chat = new GameChat();
chat.RegisterStringReplacement("%NAME", ctx => ctx.Source.Name);

Tokens are matched ignoring case, and the longest token wins when one contains another. A value is inserted as it is, so a player named %NAME stays %NAME. A null value is inserted as nothing. Registering the same spelling twice throws.

Events

The engine raises these events:

Event	When
CommandExecuted	A command ran.
CommandNotFound	The first word matched no command.
MissingParameterOnCommand	A required parameter was left out. One event for each.
WrongParameterOnCommand	A value couldn't be converted to its parameter's type. One event for each.

A command with a missing or wrong parameter doesn't run.

using BSGameLib.Chat;

var chat = new GameChat();

chat.CommandNotFound += (_, e) => Console.WriteLine($"No command {e.Keyword}");
chat.MissingParameterOnCommand += (_, e) => Console.WriteLine($"Missing {e.Parameter.Name}");
chat.WrongParameterOnCommand += (_, e) => Console.WriteLine($"{e.Value} is not a valid {e.Parameter.Name}");
chat.CommandExecuted += (_, e) => Console.WriteLine($"Ran {e.Keyword}");

Describing commands to players

DescribeCommands() lists the registered commands, with their keywords, help text and parameters. A client needs the same information to complete a line as the player types it, so the server sends it in a packet of its own design. CommandSpec is plain data made for that: its From method turns a description into one.

CommandCompleter works out what a line being typed could be: the command or sub-command names, then the parameter values the game knows, and a hint of what is still to type. The values come from a function you pass in. It receives the parameter's Suggestions name and the arguments typed before it.

using BSGameLib.Chat;

var chat = new GameChat();
var specs = chat.DescribeCommands().Select(CommandSpec.From).ToList();
var completer = new CommandCompleter(specs);

var result = completer.Complete("/gi", (suggestion, arguments) => Array.Empty<string>());
Console.WriteLine($"Options: {string.Join(", ", result.Options)}; hint: {result.Hint}");

ChatHistory keeps the lines a player has sent, for the Up and Down keys. Back and Forward return the line to show, and keep what was being typed when the player steps away from it:

using BSGameLib.Chat;

var history = new ChatHistory(100);
history.Add("/roll 20");

var shown = history.Back("/ro");
var newer = history.Forward(shown);
Console.WriteLine($"{shown} then {newer}");