Building a Simple Character
To build a character for nsquared agents, create a .NET 10 class library with a class that
implements the IAgent interface. Install the current .NET 10 SDK and use the
latest stable nsquared.agents.api NuGet package.
You will also need to have some images for the animated frames of the character. In this example we are using a small set of images to create a simple clippy character. These frames can be found in the sample Frames folder.
Step-by-Step creating a simple nsquared agent character
-
Start by creating a new C# class library project named SimpleCharacter.
dotnet new classlib --name SimpleCharacterThis will create a new folder named SimpleCharacter containing C# project named SimpleCharacter, and a code file named Class1.cs.
- Rename the file
Class1.cstoCharacter.cs -
Rename the class in the code to
Characternamespace SimpleCharacter; public class Character { } -
In the
SimpleCharacter.csprojfile set the target framework and plugin file extension:<TargetFramework>net10.0</TargetFramework> <TargetExt>.Agent</TargetExt> -
Add the API and Avalonia packages:
dotnet add package nsquared.agents.api dotnet add package Avaloniadotnet add packageselects the latest stable package unless a version is specified. - In the SimpleCharacter folder create a new folder named
Assets. - In the new
Assetsfolder create a folder namedFrames. - In the
Framesfolder copy the frame images from the sample Frames folder. - In the
Assetsfolder create a file namedActions.json. Define the animation actions and states in this file. See the Actions.json schema for the field reference. -
Edit the
Actions.jsonfile and put the following json to define two actions and two states.{ "ActionItems": [ { "Name": "Show", "Return": null, "Frames": [ { "SoundEffect": null, "Duration": 10, "ExitBranch": -1, "Images": [ { "Filename": "0000", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [] } ], "Reverse": false, "ActionMenuSelected": null }, { "Name": "Idle", "Return": null, "Frames": [ { "SoundEffect": null, "Duration": 10, "ExitBranch": -1, "Images": [ { "Filename": "0000", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [] }, { "SoundEffect": null, "Duration": 10, "ExitBranch": -1, "Images": [ { "Filename": "0045", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [] }, { "SoundEffect": null, "Duration": 10, "ExitBranch": -1, "Images": [ { "Filename": "0046", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [] }, { "SoundEffect": null, "Duration": 10, "ExitBranch": 9, "Images": [ { "Filename": "0047", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [] }, { "SoundEffect": null, "Duration": 10, "ExitBranch": 9, "Images": [ { "Filename": "0048", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [] }, { "SoundEffect": null, "Duration": 10, "ExitBranch": -1, "Images": [ { "Filename": "0049", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [ { "BranchTo": 8, "Probability": 3 } ] }, { "SoundEffect": null, "Duration": 15, "ExitBranch": 8, "Images": [ { "Filename": "0050", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [ { "BranchTo": 7, "Probability": 98 }, { "BranchTo": 6, "Probability": 2 } ] }, { "SoundEffect": null, "Duration": 10, "ExitBranch": 9, "Images": [ { "Filename": "0051", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [] }, { "SoundEffect": null, "Duration": 10, "ExitBranch": -1, "Images": [ { "Filename": "0052", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [] }, { "SoundEffect": null, "Duration": 10, "ExitBranch": -1, "Images": [ { "Filename": "0053", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [] }, { "SoundEffect": null, "Duration": 10, "ExitBranch": -1, "Images": [ { "Filename": "0000", "OffsetX": 0, "OffsetY": 0 } ], "Mouths": [], "Branches": [] } ], "Reverse": false, "ActionMenuSelected": null } ], "States": { "Showing": [ "Show" ], "IdlingLevel1": [ "Idle" ] } } -
Include assets using the resource type expected by
IAgent. CreateAssets\Audioand addAssets\Icon.icoif using the paths shown below:<ItemGroup> <AvaloniaResource Include="Assets\**" /> <AvaloniaResource Remove="Assets\Audio\**" /> <None Remove="Assets\Frames\**" /> <EmbeddedResource Include="Assets\Audio\**" /> </ItemGroup> -
Edit
Character.csto implementIAgent.WakeWord,Personality, andVoiceare optional; override them to customize voice activation and AI responses for the character.using nsquared.agents; namespace SimpleCharacter; public class Character : IAgent { public string Name { get; set; } = "SimpleCharacter"; public string AssemblyName { get; set; } = "SimpleCharacter"; public Uri ActionsFileUri => new($"avares://{AssemblyName}/Assets/Actions.json"); public string AudioFilesPath => $"{Name}.Assets.Audio."; public string FrameAssetPath => $"avares://{AssemblyName}/Assets/Frames/"; public string IconPath => $"avares://{AssemblyName}/Assets/Icon.ico"; public string WakeWord => "SimpleCharacter"; public string? Personality => "You are a friendly, concise desktop assistant."; public string? Voice => null; } -
Build the SimpleCharacter project. It should build the
SimpleCharacter.Agentfile in a bin folder. -
Run the nsquared agents application and open Settings, and then go to the
Addbutton next to the character list
-
This will open a file dialog. Find the
SimpleCharacter.Agentfile you built.
-
The new SimpleCharacter will be selected
