SadConsole 10.4.0

dotnet add package SadConsole --version 10.4.0
NuGet\Install-Package SadConsole -Version 10.4.0
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="SadConsole" Version="10.4.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SadConsole --version 10.4.0
#r "nuget: SadConsole, 10.4.0"
#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.
// Install SadConsole as a Cake Addin
#addin nuget:?package=SadConsole&version=10.4.0

// Install SadConsole as a Cake Tool
#tool nuget:?package=SadConsole&version=10.4.0

SadConsole Logo

Chat on discord NuGet

SadConsole is a C#-based .NET cross-platform terminal, ascii, console, game engine. It simulates these types of programs and with it you can make ascii-styled games for modern platforms. At its heart, SadConsole is really a giant tile-based game engine. However, its object model is conceptually similar to a traditional console app.

While SadConsole is a generic library that doesn't provide any rendering capabilities, "host" libraries are provided that add renderers to SadConsole. The two hosts provided by this library are for SadConsole.Host.MonoGame and SadConsole.Host.SFML. When adding a host library to your project, you don't need to reference the base SadConsole package. If you use MonoGame, you'll also need to add a rendering NuGet package, such as MonoGame.Framework.DesktopGL.

SadConsole currently targets .NET 6, .NET 7, and .NET 8

For the latest changes in this release, see the notes below

Features

Here are some of the features SadConsole supports:

  • Show any number of consoles of any size.
  • Uses graphical tile-based images to build out an ASCII-character font with support for more than 256 characters.
  • Fonts are simply sprite sheet tilesets tied to ascii codes, you can use full graphical tiles if you want.
  • Use more than one font file. However, each console is restricted to a single font.
  • Full GUI system for interactive controls such as list boxes, buttons, and text fields.
  • Importers for DOS ANSI files, TheDraw text fonts, RexPaint, and Playscii.
  • Animated consoles and instruction system to chain commands together.
  • String encoding system for colors and effects while printing.
  • Entity support for drawing thousands of movable objects on the screen
  • Translating images to text-blocks.
  • Keyboard and mouse support.
  • Highly customizable framework.
String display and parsing

string pic

GUI library

GUI library pic

Scrolling

scrolling console

Example startup code

using Console = SadConsole.Console;
using SadConsole;
using SadConsole.Configuration;
using SadRogue.Primitives;

Settings.WindowTitle = "SadConsole Examples";

// Configure how SadConsole starts up
Builder startup = new Builder()
    .SetScreenSize(90, 30)
    .UseDefaultConsole()
    .OnStart(Game_Started)
    .IsStartingScreenFocused(true)
    .ConfigureFonts(true)
    ;

// Setup the engine and start the game
Game.Create(startup);
Game.Instance.Run();
Game.Instance.Dispose();

void Game_Started(object? sender, GameHost host)
{
    ColoredGlyph boxBorder = new(Color.White, Color.Black, 178);
    ColoredGlyph boxFill = new(Color.White, Color.Black);

    Game.Instance.StartingConsole.FillWithRandomGarbage(255);
    Game.Instance.StartingConsole.DrawBox(new Rectangle(2, 2, 26, 5), ShapeParameters.CreateFilled(boxBorder, boxFill));
    Game.Instance.StartingConsole.Print(4, 4, "Welcome to SadConsole!");
}
Imports SadConsole
Imports Console = SadConsole.Console
Imports SadConsole.Configuration
Imports SadRogue.Primitives

Module Module1

    Sub Main()

        Dim startup As New Builder()

        ' Configure how SadConsole starts up
        startup.SetScreenSize(90, 30)
        startup.UseDefaultConsole()
        startup.OnStart(AddressOf Game_Started)
        startup.IsStartingScreenFocused(True)
        startup.ConfigureFonts(True)

        ' Setup the engine and start the game
        SadConsole.Game.Create(startup)
        SadConsole.Game.Instance.Run()
        SadConsole.Game.Instance.Dispose()

    End Sub

    Sub Game_Started(sender As Object, host As GameHost)

        Dim boxBorder = New ColoredGlyph(Color.White, Color.Black, 178)
        Dim boxFill = New ColoredGlyph(Color.White, Color.Black)

        Game.Instance.StartingConsole.FillWithRandomGarbage(255)
        Game.Instance.StartingConsole.DrawBox(New Rectangle(2, 2, 26, 5), ShapeParameters.CreateFilled(boxBorder, boxFill))
        Game.Instance.StartingConsole.Print(4, 4, "Welcome to SadConsole!")

    End Sub

End Module

Latest changes

v10.4.0 (03/31/2024)

New versioning system. Versions for SadConsole will be in the following format: [all libs major].[all libs minor].[individual lib revision]

When patches come out for the indvidual libraries, the X in 10.0.X would increment. These would be like host updates, or the extended library, but not public facing changes in SadConsole itself. If SadConsole itself updates, the X in 10.X.0 would increment. All libraries would increment with SadConsole, and the individual lib revisions would reset to 0. The X on X.0.0 would indicate a major change to SadConsole with most likely a lot of bigger breaking changes.

That said, SadConsole is resetting all versions to v10.4.0 for this release. From now on, the new versioning system is in place.

  • [Breaking] A minor breaking change. If you were creating your own IConfigurator startup configs, the Run method's parameter changed from Game to GameHost.

  • [Core] Added Components.Overlay which displays a surface on top of an existing console/surface object as a top layer.

  • [Core] Bug: Font.OnFontChanged wasn't actually being called. It is now.

  • [Core] Added Coroutine NuGet library. This is included now with SadConsole.

  • [Core] Added CoroutineHandlerComponent which is a manager that you can add to an object and coroutines to.

  • [Core] Cursor.PrintCoroutine which prints as a coroutine, pausing at each character.

  • [Core] Instructions.DrawString updated to use Cursor.PrintCoroutine which lets it pretty print word breaks.

  • [Core] XML docs didn't genereate correctly for the last build.

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (8)

Showing the top 5 NuGet packages that depend on SadConsole:

Package Downloads
SadCanvas

A canvas class that works with SadConsole and MonoGame host.

SadConsole.Extended

A library of common classes that extend SadConsole with new controls, windows, and more.

SadConsole.Host.MonoGame

A graphics hosting library for SadConsole that targets MonoGame.

SadConsole.Host.SFML

A graphics hosting library for SadConsole that targets SFML.

SadConsole.GoRogueHelpers

A helper library for SadConsole games built with GoRogue.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on SadConsole:

Repository Stars
Thraka/SadConsole
A .NET ascii/ansi console engine written in C# for MonoGame and XNA. Create your own text roguelike (or other) games!
Version Downloads Last updated
10.4.0 416 3/31/2024
10.4.0-debug 145 3/31/2024
10.0.3 332 3/14/2024
10.0.3-debug 202 3/14/2024
10.0.2 1,446 11/10/2023
10.0.2-debug 832 11/10/2023
10.0.1 719 11/10/2023
10.0.1-debug 687 11/10/2023
10.0.0 1,534 10/29/2023
10.0.0-debug 940 10/29/2023
10.0.0-beta3-debug 1,049 10/14/2023
10.0.0-beta3 988 10/14/2023
10.0.0-beta2-debug 999 10/11/2023
10.0.0-beta2 1,013 10/11/2023
10.0.0-beta1-debug 1,025 10/11/2023
10.0.0-beta1 1,057 10/11/2023
10.0.0-alpha4-debug 1,318 8/26/2023
10.0.0-alpha4 1,254 8/26/2023
10.0.0-alpha3-debug 1,168 8/26/2023
10.0.0-alpha3 1,182 8/26/2023
10.0.0-alpha2-debug 1,547 6/18/2023
10.0.0-alpha2 1,330 6/18/2023
10.0.0-alpha1-debug 1,435 6/4/2023
9.2.2 4,809 1/22/2022
9.2.2-debug 1,145 1/22/2022
9.2.1 2,373 1/4/2022
9.2.0 3,201 12/31/2021
9.2.0-debug 1,059 12/31/2021
9.1.1 5,093 8/7/2021
9.1.1-debug 1,241 8/7/2021
9.1.0 2,023 7/6/2021
9.1.0-debug 1,234 7/6/2021
9.0.0 4,459 6/6/2021
9.0.0-debug 1,213 6/6/2021
9.0.0-beta4 1,887 1/15/2021
9.0.0-beta3 1,993 12/19/2020
9.0.0-beta2 1,516 10/9/2020
9.0.0-beta1 1,637 8/1/2020
9.0.0-alpha9 1,653 7/25/2020
9.0.0-alpha8 1,362 7/13/2020
9.0.0-alpha7 1,665 7/11/2020
9.0.0-alpha6 1,707 5/28/2020
9.0.0-alpha5 1,508 5/26/2020
9.0.0-alpha4 1,384 5/1/2020
9.0.0-alpha3 1,544 5/1/2020
9.0.0-alpha2 1,473 3/14/2020
9.0.0-alpha1 1,825 1/26/2020
8.99.3 3,636 8/15/2020
8.99.3-debug 1,427 8/15/2020
8.99.2 1,744 7/14/2020
8.99.2-debug 1,381 7/14/2020
8.99.1 2,374 4/11/2020
8.99.1-debug 1,388 4/11/2020
8.99.0 2,411 11/27/2019
8.99.0-debug 1,386 11/27/2019
8.9.1 3,740 11/5/2019
8.9.1-debug 1,376 11/5/2019
8.9.0 2,124 9/7/2019
8.9.0-debug 1,571 9/7/2019
8.8.1 2,958 7/28/2019
8.8.1-debug 1,553 7/28/2019
8.8.0 2,306 7/27/2019
8.8.0-debug 1,497 7/27/2019
8.7.1 1,874 6/22/2019
8.7.1-debug 1,553 6/22/2019
8.7.0 1,732 6/22/2019
8.7.0-debug 1,573 6/22/2019
8.6.0 1,994 4/14/2019
8.6.0-debug 1,580 4/14/2019
8.5.0 1,901 4/2/2019
8.5.0-debug 1,606 4/2/2019
8.4.1 1,859 3/19/2019
8.4.1-debug 1,639 3/19/2019
8.4.0 1,725 3/17/2019
8.4.0-debug 1,574 3/17/2019
8.3.0 1,820 3/10/2019
8.3.0-debug 1,568 3/10/2019
8.2.0 1,862 3/2/2019
8.2.0-debug 1,641 3/2/2019
8.1.0 1,824 2/28/2019
8.1.0-debug 1,564 2/28/2019
8.0.0 1,908 2/24/2019
8.0.0-pre5 1,611 2/19/2019
8.0.0-pre4 1,649 1/31/2019
8.0.0-pre2 1,692 12/30/2018
8.0.0-pre1 1,658 12/30/2018
7.3.0 1,983 12/29/2018
7.2.0 2,065 11/20/2018
7.1.0 2,108 10/19/2018
7.0.4 2,057 9/8/2018
7.0.3 1,921 9/8/2018
7.0.2 2,251 8/31/2018
7.0.0 2,033 8/29/2018
7.0.0-pre1 1,741 8/22/2018
6.5.0 2,219 6/12/2018
6.4.11 2,266 4/13/2018
6.4.11-pre1 2,067 4/6/2018
6.4.10 2,230 3/18/2018
6.4.9 2,181 3/18/2018
6.4.8 2,149 3/18/2018
6.4.7 2,216 3/16/2018
6.4.6 2,426 2/14/2018
6.4.5 2,239 2/3/2018
6.4.3 2,218 11/14/2017
6.4.2 2,312 8/11/2017
6.4.1 2,127 8/10/2017
6.4.0 2,212 7/25/2017
6.3.0 2,232 6/9/2017
6.2.2 2,237 5/20/2017
6.2.1 2,346 4/23/2017
6.2.0 2,159 4/22/2017
6.1.4 2,158 4/17/2017
6.1.3 2,852 4/3/2017
6.1.2 2,126 4/1/2017
6.1.1 2,092 4/1/2017
6.1.0 2,106 3/31/2017
6.0.1 2,227 3/19/2017
6.0.0 2,036 3/18/2017

- Reversioned to follow new versioning scheme.
- Configuration namespace and related types was moved here from the hosts.
- Added Components.Overlay which displays a surface on top of an existing console/surface object as a top layer.
- Bug: Font.OnFontChanged wasn't actually being called. It is now.
- Added Coroutine NuGet library. This is included now with SadConsole.
- Added CoroutineHandlerComponent which is a manager that you can add to an object and coroutines to.
- Cursor.PrintCoroutine which prints as a coroutine, pausing at each character.
- Instructions.DrawString updated to use Cursor.PrintCoroutine which lets it pretty print word breaks.
- XML docs didn't genereate correctly for the last build.