SadConsole 10.0.0-alpha2

This is a prerelease version of SadConsole.
There is a newer version of this package available.
See the version list below for details.
dotnet add package SadConsole --version 10.0.0-alpha2                
NuGet\Install-Package SadConsole -Version 10.0.0-alpha2                
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.0.0-alpha2" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add SadConsole --version 10.0.0-alpha2                
#r "nuget: SadConsole, 10.0.0-alpha2"                
#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.0.0-alpha2&prerelease

// Install SadConsole as a Cake Tool
#tool nuget:?package=SadConsole&version=10.0.0-alpha2&prerelease                

SadConsole Logo

Chat on discord NuGet

SadConsole is a generic library that emulates old-school console game systems. It provides command prompt-style graphics where one or more tile textures are used to represent an ASCII character set. Console's are made up of a grid of cells, each of which can have its own foreground, background, glyph, and special effect applied to it.

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 MonoGame and SFML.

SadConsole currently targets .NET 6.

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.
  • Uses graphical tile-based images to build out an ASCII-character font with support for more than 256 characters.
  • Use more than one font file. However, each console is restricted to a single font.
  • Independently controlled entities for game objects.
  • Keyboard and Mouse support.
  • Text UI control framework.
  • Windowing capabilities.
  • Importers for DOS ANSI files, TheDraw text fonts, RexPaint, and Playscii.
  • Animation support.
  • Translating images to text-blocks.
  • Highly customizable system.
String display and parsing

string pic

GUI library

GUI library pic

Scrolling

scrolling console

Dependencies

SadConsole uses NuGet for its .NET dependencies:

Example startup code

using SadConsole;

Settings.WindowTitle = "SadConsole Examples";

Game.Configuration gameStartup = new Game.Configuration()
    .SetScreenSize(90, 30)
    .OnStart(onStart)
    .IsStartingScreenFocused(false)
    .ConfigureFonts((f) => f.UseBuiltinFontExtended())
    ;

Game.Create(gameStartup);
Game.Instance.Run();
Game.Instance.Dispose();

void onStart()
{
    ColoredGlyph boxBorder = new ColoredGlyph(Color.White, Color.Black, 178);
    ColoredGlyph 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!");
}

Latest changes v10.0.0 Alpha 1 (XX/XX/2023)

Major changes (possibly breaking)

  • [Core] The editor functions that changed glyphs and printed on consoles have moved from being extension methods for the ICellSurface interface to the ISurface interface. Console, IScreenSurface, and ICellSurface, all implement this new interface. This means you can now use the editing extensions directly on those objects.
  • [Core] Because Console no longer implements ICellSurface, and instead implements ISurface, some properties have been moved to the Surface property, such as myConsole.TimesShiftedUp is now myConsole.Surface.TimesShiftedUp.

New features

  • [Core] Added Componenets.LayeredSurface component. Add this component to a ScreenSurface to enable multiple surface layers. Use the LayeredSurface to manage the layers.
  • [UI] New control, NumberBox. The IsNumeric system was removed from the TextBox and put into its own control.

Normal changes

  • Target .NET 6+ exclusively. Core library is nullable aware.
  • [Core] Splash screen printing wasn't being shown because of cursor changes.
  • [Core] IFont now defines glyph definitions.
  • [Core] Various SadFont properties and methods are now settable/callable.
  • [Core] Extensions methods added to hosts to allow manipulation of font textures.
  • [Core] Settings.CreateStartingConsole setting added to avoid creating the StartingConsole.
  • [Core] Cursor now has the property DisablePrintAutomaticLineFeed which, when true, prevents the cursor from moving to the next line if printing a character at the end of the current line.
  • [Core] Ansi.AnsiWriter handles sauce now by ignoring the rest of a document once character 26 (CTRL-Z) is encountered.
  • [Core] Ansi.AnsiWriter has always used a cursor to print, it now sets UseLinuxLineEndings = true and DisablePrintAutomaticLineFeed = true.
  • [Core] Added SadConsole.SplashScreens.Ansi1 splashscreen, the new SadConsole logo, for use with games.
  • [Core] Added ScreenSurface.QuietSurfaceHandling property. When true, this property prevents the .Surface property from raising events and calling virtual methods when the instance changes. This is useful for AnimatedScreenSurface instances that have fast moving animations.
  • [Core] The Entity type now supports animated surfaces. When creating an entity, you must specify it as a single cell entity or animated surface entity.
  • [Core] The effects system had a bug where if you added the same effect with the same cell twice, and the effect should restore the cell state, it wouldn't.
  • [Core] AsciiKey used by the keyboard system now detects capslock and shifted state to produce capital or lowercase letters.
  • [Core] AsciiKey exposes a bunch of static dictionaries that help with remapping keys and characters.
  • [Core] ColoredGlyph.IsVisible now sets ColoredGlyph.IsDirty to true when its value changes.
  • [Core] Surface.RenderSteps moved to the renderer.
  • [Core] RenderSteps is now a List and you must call RenderSteps.Sort(SadConsole.Renderers.RenderStepComparer.Instance) when the collection is changed.
  • [Core] Instructions.DrawString uses System.TimeSpan now, and is more accurate.
  • [Core] Effects have a RunEffectOnApply property that will run the effect.Update method once, with a duration of zero, when the effect is added to a manager.
  • [Core] EffectsManager will apply the active effect to a cell right when the cell is added to the effect. This was happening on the next render frame.
  • [Core] Surface shifting is much more performant (Thanks Chris3606)
  • [Core] Cursor has some new methods for erasing: Erase, EraseUp, EraseDown, EraseLeft, EraseRight, EraseColumn, EraseRow.
  • [Core] Mouse state object now tracks *ButtonDownDuration times. When the button is down and the time is zero, this indicates the button was just pressed. Otherwise, you can detect how long the button has been held down.
  • [Core] Rename RexPaint ToLayersComponent to ToCellSurface.
  • [Core] Rework Timer with Start/Stop/Restart methods.
  • [UI] Scroll bar with a size of 3 now disables the middle area, and you can use a size of 2 now.
  • [UI] Scroll bar supports a thickness other than 1.
  • [UI] Control host would get stuck when tabbing to a control that was disabled. Now it skips the control.
  • [UI] TextBox rewritten. The IsNumeric system was removed and added to a new control: NumberBox. The TextBox no longer has an editing mode and simply starts editing as it's focused and stops editing once it loses focus.
  • [UI] ControlBase.IsDirty property now calls the protected OnIsDirtyChanged method which then raises the IsDirtyChanged event.
  • [UI] Panel control uses CompositeControl as a base class. Theme supports lines as a border of the panel.
  • [UI] Ven0maus added the Table control.
  • [ExtendedLib] Border control uses view size now instead of full size of wrapping object.
  • [ExtendedLib] Border.AddToSurface/Window has been renamed to Border.CreateForSurface/Window.

Removed

  • [Core] Algorithms.Line\Circle\Ellipse have been removed. The latest primitives library provides these methods.
  • [Core] Shapes namespace removed. The latest primitives library release that SadConsole uses, provides these.

Host changes

  • [MonoGame] NuGet package has a -windows framework target that targets DirectX and adds support for WPF.
  • [MonoGame] Fix conversion of Mirror to SpriteEffects.
  • [MonoGame\SFML] Surface renderers now skip the glyph if the glyph is 0.
  • [MonoGame\SFML] New SurfaceDirtyCells renderer added which only draws cells that are marked dirty.
  • [MonoGame\SFML] New Game.Configuration object used for creating a SadConsole game.
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 was computed.  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
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.

TheSadRogue.Integration

An official integration library for using GoRogue and SadConsole together to create a roguelike.

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.5.0 345 12/7/2024
10.5.0-debug 101 12/7/2024
10.4.2 246 10/24/2024
10.4.2-debug 70 10/24/2024
10.4.1 1,247 6/13/2024
10.4.1-debug 151 6/13/2024
10.4.0 1,276 3/31/2024
10.4.0-debug 212 3/31/2024
10.0.3 486 3/14/2024
10.0.3-debug 259 3/14/2024
10.0.2 1,573 11/10/2023
10.0.2-debug 876 11/10/2023
10.0.1 753 11/10/2023
10.0.1-debug 721 11/10/2023
10.0.0 1,799 10/29/2023
10.0.0-debug 988 10/29/2023
10.0.0-beta3-debug 1,101 10/14/2023
10.0.0-beta3 1,067 10/14/2023
10.0.0-beta2-debug 1,050 10/11/2023
10.0.0-beta2 1,071 10/11/2023
10.0.0-beta1-debug 1,078 10/11/2023
10.0.0-beta1 1,117 10/11/2023
10.0.0-alpha4-debug 1,368 8/26/2023
10.0.0-alpha4 1,301 8/26/2023
10.0.0-alpha3-debug 1,212 8/26/2023
10.0.0-alpha3 1,229 8/26/2023
10.0.0-alpha2-debug 1,596 6/18/2023
10.0.0-alpha2 1,390 6/18/2023
10.0.0-alpha1-debug 1,492 6/4/2023
9.2.2 5,064 1/22/2022
9.2.2-debug 1,189 1/22/2022
9.2.1 2,447 1/4/2022
9.2.0 3,315 12/31/2021
9.2.0-debug 1,079 12/31/2021
9.1.1 5,399 8/7/2021
9.1.1-debug 1,270 8/7/2021
9.1.0 2,136 7/6/2021
9.1.0-debug 1,258 7/6/2021
9.0.0 4,632 6/6/2021
9.0.0-debug 1,259 6/6/2021
9.0.0-beta4 1,946 1/15/2021
9.0.0-beta3 2,054 12/19/2020
9.0.0-beta2 1,574 10/9/2020
9.0.0-beta1 1,695 8/1/2020
9.0.0-alpha9 1,706 7/25/2020
9.0.0-alpha8 1,396 7/13/2020
9.0.0-alpha7 1,734 7/11/2020
9.0.0-alpha6 1,767 5/28/2020
9.0.0-alpha5 1,562 5/26/2020
9.0.0-alpha4 1,408 5/1/2020
9.0.0-alpha3 1,604 5/1/2020
9.0.0-alpha2 1,497 3/14/2020
9.0.0-alpha1 1,921 1/26/2020
8.99.3 3,709 8/15/2020
8.99.3-debug 1,450 8/15/2020
8.99.2 1,779 7/14/2020
8.99.2-debug 1,410 7/14/2020
8.99.1 2,434 4/11/2020
8.99.1-debug 1,411 4/11/2020
8.99.0 2,473 11/27/2019
8.99.0-debug 1,407 11/27/2019
8.9.1 3,844 11/5/2019
8.9.1-debug 1,414 11/5/2019
8.9.0 2,180 9/7/2019 8.9.0 is deprecated because it is no longer maintained.
8.9.0-debug 1,599 9/7/2019 8.9.0-debug is deprecated because it is no longer maintained.
8.8.1 3,041 7/28/2019 8.8.1 is deprecated because it is no longer maintained.
8.8.1-debug 1,577 7/28/2019 8.8.1-debug is deprecated because it is no longer maintained.
8.8.0 2,358 7/27/2019 8.8.0 is deprecated because it is no longer maintained.
8.8.0-debug 1,517 7/27/2019 8.8.0-debug is deprecated because it is no longer maintained.
8.7.1 1,917 6/22/2019 8.7.1 is deprecated because it is no longer maintained.
8.7.1-debug 1,579 6/22/2019 8.7.1-debug is deprecated because it is no longer maintained.
8.7.0 1,764 6/22/2019 8.7.0 is deprecated because it is no longer maintained.
8.7.0-debug 1,598 6/22/2019 8.7.0-debug is deprecated because it is no longer maintained.
8.6.0 2,042 4/14/2019 8.6.0 is deprecated because it is no longer maintained.
8.6.0-debug 1,604 4/14/2019 8.6.0-debug is deprecated because it is no longer maintained.
8.5.0 1,937 4/2/2019 8.5.0 is deprecated because it is no longer maintained.
8.5.0-debug 1,630 4/2/2019 8.5.0-debug is deprecated because it is no longer maintained.
8.4.1 1,895 3/19/2019 8.4.1 is deprecated because it is no longer maintained.
8.4.1-debug 1,665 3/19/2019 8.4.1-debug is deprecated because it is no longer maintained.
8.4.0 1,756 3/17/2019 8.4.0 is deprecated because it is no longer maintained.
8.4.0-debug 1,598 3/17/2019 8.4.0-debug is deprecated because it is no longer maintained.
8.3.0 1,862 3/10/2019 8.3.0 is deprecated because it is no longer maintained.
8.3.0-debug 1,589 3/10/2019 8.3.0-debug is deprecated because it is no longer maintained.
8.2.0 1,900 3/2/2019 8.2.0 is deprecated because it is no longer maintained.
8.2.0-debug 1,671 3/2/2019 8.2.0-debug is deprecated because it is no longer maintained.
8.1.0 1,858 2/28/2019 8.1.0 is deprecated because it is no longer maintained.
8.1.0-debug 1,589 2/28/2019 8.1.0-debug is deprecated because it is no longer maintained.
8.0.0 1,958 2/24/2019 8.0.0 is deprecated because it is no longer maintained.
8.0.0-pre5 1,641 2/19/2019 8.0.0-pre5 is deprecated because it is no longer maintained.
8.0.0-pre4 1,672 1/31/2019 8.0.0-pre4 is deprecated because it is no longer maintained.
8.0.0-pre2 1,722 12/30/2018 8.0.0-pre2 is deprecated because it is no longer maintained.
8.0.0-pre1 1,689 12/30/2018 8.0.0-pre1 is deprecated because it is no longer maintained.
7.3.0 2,020 12/29/2018
7.2.0 2,112 11/20/2018 7.2.0 is deprecated because it is no longer maintained.
7.1.0 2,149 10/19/2018 7.1.0 is deprecated because it is no longer maintained.
7.0.4 2,096 9/8/2018 7.0.4 is deprecated because it is no longer maintained.
7.0.3 1,956 9/8/2018 7.0.3 is deprecated because it is no longer maintained.
7.0.2 2,312 8/31/2018 7.0.2 is deprecated because it is no longer maintained.
7.0.0 2,077 8/29/2018
7.0.0-pre1 1,780 8/22/2018 7.0.0-pre1 is deprecated because it is no longer maintained.
6.5.0 2,268 6/12/2018
6.4.11 2,313 4/13/2018 6.4.11 is deprecated because it is no longer maintained.
6.4.11-pre1 2,101 4/6/2018 6.4.11-pre1 is deprecated because it is no longer maintained.
6.4.10 2,269 3/18/2018 6.4.10 is deprecated because it is no longer maintained.
6.4.9 2,226 3/18/2018 6.4.9 is deprecated because it is no longer maintained.
6.4.8 2,193 3/18/2018 6.4.8 is deprecated because it is no longer maintained.
6.4.7 2,275 3/16/2018 6.4.7 is deprecated because it is no longer maintained.
6.4.6 2,474 2/14/2018 6.4.6 is deprecated because it is no longer maintained.
6.4.5 2,292 2/3/2018 6.4.5 is deprecated because it is no longer maintained.
6.4.3 2,272 11/14/2017 6.4.3 is deprecated because it is no longer maintained.
6.4.2 2,355 8/11/2017 6.4.2 is deprecated because it is no longer maintained.
6.4.1 2,178 8/10/2017 6.4.1 is deprecated because it is no longer maintained.
6.4.0 2,256 7/25/2017 6.4.0 is deprecated because it is no longer maintained.
6.3.0 2,275 6/9/2017 6.3.0 is deprecated because it is no longer maintained.
6.2.2 2,283 5/20/2017 6.2.2 is deprecated because it is no longer maintained.
6.2.1 2,394 4/23/2017 6.2.1 is deprecated because it is no longer maintained.
6.2.0 2,200 4/22/2017 6.2.0 is deprecated because it is no longer maintained.
6.1.4 2,197 4/17/2017 6.1.4 is deprecated because it is no longer maintained.
6.1.3 2,893 4/3/2017 6.1.3 is deprecated because it is no longer maintained.
6.1.2 2,165 4/1/2017 6.1.2 is deprecated because it is no longer maintained.
6.1.1 2,128 4/1/2017 6.1.1 is deprecated because it is no longer maintained.
6.1.0 2,149 3/31/2017 6.1.0 is deprecated because it is no longer maintained.
6.0.1 2,269 3/19/2017 6.0.1 is deprecated because it is no longer maintained.
6.0.0 2,073 3/18/2017

...