How to Use LSN in Your Game - Paramecium13/LSN GitHub Wiki

...

Interfaces

In order for a game to run LSN scripts, it needs to implement three different interfaces to use LSN.

IInterpreter

This interface defines the LSN Interpreter, which is used to execute LSN code. Many of the methods it defines are used to run general purpose LSN code that does not directly interact with the game. For example, using variables and calling functions. These functions are implemented by the Interpreter abstract class. Users are strongly recommended to implement IInterpreter by extending Interpreter and implementing its abstract methods.

The abstract methods of Interpreter that need to be implemented are used to execute game specific functionality in certain LSN statements and/or control structures. For most of these methods, you are free to use their parameters as you want so as to make the corresponding LSN code behave how you want for your game. For example, in the GiveItem and GiveGold methods, you may assume that the target parameter is an instance of a specific host interface that wraps a specific type of object in your game, such as a character or a container. Or you may decide that is is a string or integer that uniquely identifies an inventory. Or you could allow it to be either one and handle it accordingly. These are the abstract methods of Interpreter that need to be implemented:

void GiveItemTo(LsnValue id, int amount, LsnValue target): This method is called by the give item statement in LSN. The id parameter is meant to be the unique id of the item to give (or take). It may be an integer, a string, or whatever; LSNr does not restrict its type. The amount parameter is, obviously, the amount of the item to give. If it is negative, the assumption is that that amount will be removed from the target. The LSN source code may choose not to specify an amount, which means that only one item is being given and LSNr provides the value of 1. The target parameter represent the character or container that will receive (or lose) the item(s). The LSN source code may not specify a target, in which case LSNr provides the value of nil. When the value is nil, the assumption is that it applies to the player character. But, as mentioned above, you are free to interpret the parameters to mean whatever you want them to and act accordingly.
void GiveGoldTo(int amount, LsnValue target): This method is called by the give gold statement in LSN. It is essentially the same as give item, except that the item being given is gold (or whatever currency your game's world uses).
void Say(string message, LsnValue graphic, string title): This method is called by the say statement in LSN. It is intended to be used to display a message on screen to the player. The message parameter is the text to be displayed on screen. If you want to use some sort of text formatting in your messages, such as different colors, feel free to do so. The graphic parameter is meant to be some sort of identifier for a graphic to be displayed with the message. Unless the LSN source code specifies a value for it, its value is nil. Feel free to interpret it however you want. The title parameter is meant to be a title of sorts for the message, perhaps the name of the speaker. Unless the LSN source code specifies a value for it, it has a value of null. Feel free to interpret it however you want. It is strongly recommended that this method does not return until the player has dismissed the message or it has otherwise closed.
int DisplayChoices(): This method is called by the choice control structure. It should display a series of choices to the player and return the integer associated with that choice. The choices and their associated integers are stored in the property Choices of type IReadOnlyList<Tuple<string, int>>. The order of the choices in this list is intended to be their order in however they are displayed. It is critical that this method return the exact integer that corresponds with the choice the player selects and that it not return until the player makes a choice.

Interpreter.Run(Statement[] code, string resourceFilePath, int stackSize, LsnValue[] parameters) is the entry point for executing LSN code...

IResourceManager

This interface is used to interact with the file system(s) the game uses to store binary LSN resource files and saved data. As with IInterpreter, LSN provides a partially implemented version of IResourceManager, named ResourceManager. It has four abstract methods that need to be implemented.

ScriptObject GetUniqueScriptObject(string name): This method loads the instance of a unique script object from the saved game. Perhapse the method should also have a parameter for the path of the script file where the unique script object is defined; I think I've gone back and forth on this.
LsnResourceThing GetResourceFromFile(string path): This method loads a binary LSN file from wherever the game stores it. Implementations of this method should use the LsnResourceThing.Read(...) method to load the resource.
LsnValue[] LoadValues(string id): This method and the following method are part of a feature that is not fully implemented. When it is fully implemented, it will allow LSN functions to load and save some or all of their variables in the game's save file.
SaveValues(LsnValue[] values, string id): See above.

IHostInterface

Thr partial implementation of this is incomplete and should not be used in its current state.

IHostInterface has three methods that need to be implemented:

LsnValue CallMethod(string name, LsnValue[] arguments): This method calls a host interface method, which is implemented in the game's code... It returns the value that the host interface method returms; if it does not have a return type, it should return LsnValue.Nil.
void SubscribeToEvent(string eventName, ScriptObject eventListener): This method is used to subscribe the provided script object to this host interface's event with the given name.
void UnsubscribeToEvent(string eventName, ScriptObject eventListener): This method is used to unsubscribe the provided script object from this host interface's event with the given name.