Upgrading to API v4.0 series

Follow the compatibility notes when upgrading your mods to API v4.0 series

As API v4.0 is still in development, the breaking changes get committed and land here. They describe what broke and what should be used instead.

From 0.1.2 to 0.2.0

This version gives your kernel a minor gorgeous makeover that brings in feature additions and spectacular improvements in all fields, including some of the cosmetic changes.

Updated Terminaux to 8.1

We've updated Terminaux to 8.1 to bring improvements. However, this doesn't come without the cost of having to deal with the breaking changes, which, in this case, is many.

You can consult the list of breaking changes that result from upgrading to Terminaux 8.1 by pressing the below button:

API v8.0

Also, we have upgraded to Terminaux 8.0 earlier during the release candidate development:

API v8.0

Also, we have upgraded to Terminaux 7.0 earlier during the tech preview development:

API v7.0

Detailed important changes

This section explains how to adapt the important changes to your mod code so that it works with 0.2.0 and higher. This highlights the most important changes that we have compiled for you.

LanguagePacks addon removed

The LanguagePacks addon has been removed due to the LocaleStation migration that happened during the Terminaux 7.0 preparation stage as part of the development plans. Terminaux 7.0 Beta 4, which has been scheduled for July 31st, 2025, has incorporated langauge tools according to the tools that LocaleStation provides.

As a result, we've decided to remove the LanguagePacks addon.

Condensed the language manager

LocaleStation has been used in the whole Nitrocid kernel. We've condensed the language manager to remove all the following features:

• Custom languages

• Installation and uninstallation of custom languages

• Mod localizations

Mod localizations can be easily dealt with, but only if you've added the custom language action for your mod using the functions that LocaleStation provides.

The inter-addon communication facility will report errors when using one of the following removed functions and properties:

• ModInfo.ModStrings

• ModManager.GetLocalizedText()

As part of the condensation, we've also removed the following:

• LanguageInfo.Codepage

• LanguageInfo.Country

• LanguageInfo.Transliterable

• LanguageInfo.Custom

• public LanguageInfo(string LangName, string FullLanguageName, bool Transliterable, int Codepage = 65001, string country = "")

• public LanguageInfo(string LangName, string FullLanguageName, bool Transliterable, string[]? LanguageToken, string country = "")

Moved KernelMain to Nitrocid for the .Base migration

KernelMain.cs

public static class KernelMain

We've recently moved KernelMain from Nitrocid.Kernel to Nitrocid to satisfy the .Base migration more smoothly. This is as part of the API v4.0 version that all mods will have to use.

Due to how KernelMain is not migrated to the .Base library, you can no longer use this class. Instead, you'll have to rely on KernelReleaseInfo to get the properties that you were using.

Argument parser code moved to Terminaux 7.0

// Nitrocid.Arguments
public abstract class ArgumentExecutor : IArgument
public class ArgumentInfo
public class ArgumentParameters
public static class ArgumentParse
public interface IArgument

// Nitrocid.Arguments.Help
public static class ArgumentHelpPrint

The argument parser code has been moved to Terminaux 7.0, because the functions that are inside are application-independent. The arguments themselves haven't been moved because they are specific to Nitrocid.

We are working on the documentation of the argument parser in the Terminaux documentation, so be patient.

Remaining shell code moved to Terminaux 7.0

Features such as UESH scripting and process execution have been moved to Terminaux 7.0's shell implementation to match the Nitrocid one. Furthermore, this movement has resulted in us removing all relevant shell code, except the Nitrocid-specific code.

The shell documentation has been moved to Terminaux 7.0. Check it out using the link below:

Shells

Removed console driver

BaseConsoleDriver.cs

public abstract class BaseConsoleDriver : IConsoleDriver

ConsoleDriverTools.cs

public static class ConsoleDriverTools

IConsoleDriver.cs

public interface IConsoleDriver : IDriver

DriverHandler.cs

public static IConsoleDriver CurrentConsoleDriverLocal
public static IConsoleDriver CurrentConsoleDriver

DriverTypes.cs

public enum DriverTypes
{
    (...)
    Console,
    (...)
}

KernelDriverConfig.cs

public string CurrentConsoleDriver

The console driver has been removed following Terminaux's addition of the brand new console wrapper that doesn't rely on delegated actions. This was necessary to simplify the console wrapper feature in Terminaux and to have it handle the console driver's features.

Consult Terminaux's documentation on how to register and to set the console wrapper.

Moved theming system to Terminaux

Theming system

// Nitrocid.ConsoleBase.Colors
public enum KernelColorSetErrorReasons
public static class KernelColorTools
public enum KernelColorType

// Nitrocid.ConsoleBase.Themes
public enum ThemeCategory
public class ThemeInfo
public static class ThemePreviewTools
public enum ThemeSetErrorReasons
public static class ThemeTools

The theming system that Nitrocid used has been moved to Terminaux to give all other Terminaux applications advantage for using Nitrocid's features. Calls to text writers have also been changed to reflect the appropriate theme to set.

Consult Terminaux's documentation on how to use the theming system.

Theme-based writers moved to Terminaux

Text*Writers.cs

public static class TextDynamicWriters
public static class TextWriters

The text writers that use the theme color type have been moved to Terminaux, causing us to remove those two classes entirely. This is a massive change that will mandate the usage of what Terminaux implements due to the way the migration has been done. The relevant functions have been moved to their relevant places, resulting in the ListWriterColor being re-introduced.

Consult Terminaux's documentation on how to write to the console.

All Nitrocid functions moved to Nitrocid.Base

The root namespace for all Nitrocid functions has been changed from Nitrocid to Nitrocid.Base to separate the entry point from the actual product code, since the mods use the base library as a dependency 100% of the time. Also, it was considered to be best practice to distribute NuGet packages that result from building libraries and not .exe files.

We had planned to do this during very early development of the v0.0.x series, but we didn't do that because we had introduced kernel mods from .dll files very late.

Update your using clauses to point the root namespace of Nitrocid to Nitrocid.Base.

Calendar classes moved to Terminaux

*Calendar*.cs

// Nitrocid.Base.Kernel.Time.Calendars
public abstract class BaseCalendar : ICalendar
public static class CalendarTools
public enum CalendarTypes
public interface ICalendar

The calendar classes have been moved to Terminaux as we were working on porting the calendar cyclic writer to Terminaux to give the other console applications more features. Events and reminders, however, weren't moved due to them being Nitrocid-specific.

Those classes might get moved again to a brand new library released later this year, which will provide more features. In case this happens, we'll update both Terminaux and Nitrocid documentations to point to that library's docs.

Removed SplashClosing from the ISplash interface

ISplash.cs

bool SplashClosing { get; set; }

BaseSplash.cs

public virtual bool SplashClosing { get; set; }

Earlier, we used to allow users to override the SplashClosing property that sent signals to the kernel that the splash screen was closing. However, it worked only when the current splash instance declares that it's done.

Unfortunately, when the kernel switches to the normal splash screen as a result of an addon or a mod being unloaded, the kernel didn't realize that the splash screen needed closing, because SplashClosing was false for all other splash instances except the addon-supplied one, which is no longer found. As a result, the kernel might hang on a blank screen when trying to restart it.

This was a bad design, so we've fixed it by making the SplashClosing property in the base splash class static, while still making it available to the public. The interface definition of the same property has been removed as part of this change. This was important to fix this bug.

Please remove all overrides to this property.

Removed the legacy settings app

SettingsApp.cs

public static void OpenMainPage(string settingsType, bool useSelection = false) {}
public static void OpenMainPage(BaseKernelConfig? settingsType, bool useSelection = false) {}
public static void OpenSection(string Section, SettingsEntry SettingsSection, BaseKernelConfig settingsType)
public static void OpenKey(int KeyNumber, SettingsEntry SettingsSection, BaseKernelConfig settingsType)
public static void VariableFinder(BaseKernelConfig configType)

The legacy settings app has been finally removed, as we can't keep maintaining it anymore due to migrations and other improvements that are needed. The modern settings app is already there, and will replace the legacy settings app with the new features expected to land as development of 0.2.0 progresses.

The OpenMainPage() signatures have been changed to remove the useSelection optional parameter.

Removed the input driver

public abstract class BaseInputDriver : IInputDriver {}
public interface IInputDriver : IDriver {}
public static class InputDriverTools {}

Terminaux 7.0 has a similar functionality that allows you to change the console wrapper, which already covers input-related actions. Due to this change, we have to remove the driver.

The OpenMainPage() signatures have been changed to remove the useSelection optional parameter.

Terminaux wrapper initialization code removed

InputTools.cs

public static void InitializeTerminauxWrappers() {}

We've removed the Terminaux wrapper initialization code, because we have removed the input driver and the Nitrocid-specific console wrapper. This function was considered to be unnecessary due to a change to Terminaux 8.0.

Nitrocid now uses the standard console wrapper.

Ambient screensaver sound effects intensity changed

KernelMainConfig.cs

public bool EnableAmbientSoundFxIntense { get; set; }

We've extended the ambient sound effects for screensavers to include four levels of ambient sound effects intensity. As a result, this property had to be replaced with the AmbientSoundFxIntensity using the new enum to be able to describe those levels.

You can use the new AmbientSoundFxIntensity property to select the intensity.

Modern logon handler changed

KernelMainConfig.cs

public bool MotdHeadlineBottom { get; set; }
public bool EnableWidgets { get; set; }
public string FirstWidget { get; set; }
public string SecondWidget { get; set; }

The modern logon handler has been changed to align with the latest design philosophy that Nitrocid 0.2.0 brings. While we've preserved minimalism, we felt that the implementation was limited, so we've decided to introduce the Widget Canvas API so that you can take advantage of the powerful widget canvas that renders the widgets in any configuration you want. This makes the logon handler and The Nitrocid Homepage a lot more flexible.

Because we've introduced Widget Canvas API, the widget system is no longer exclusive to the login part of the base kernel, so we've changed its namespace to be relocated to the Misc part of the kernel. As a result, the widget system's namespace has been changed to Nitrocid.Base.Misc.Widgets.

To make pages for both the login and the homepage, you can refer to the Widget Canvas page for more information.

Modernized the speed dial feature

SpeedDialEntry.cs

public object[] Options =>
    options;

The speed dial feature, which was currently suffering from complexity due to the Options property that only stored an array of objects, has been modernized by trying to reduce the complexity, while introducing common properties, such as usernames and passwords. As a result, two new properties were created: Username and Password. To take things even further, we've changed the Options property to return a dictionary of objects so that keys can be titled, such as FtpEncryptionMode for FTP.

Speed dials created before 0.2.0 will have to be manually migrated during the release candidate stage. We'll work on a way to migrate the old speed dial files automatically to take advantage of the new features during the final release development.

Removed the Language Studio addon

KnownAddons.cs

public enum KnownAddons
{
    (...)
    LanguageStudio,
    (...)
}

The language studio has been removed as a result of the recent localization changes that have to do with the switch to the localization resources, further managed by ResourceLab.

Relying on the language studio is no longer needed.

Removed extra known addons enumeration

KnownAddons.cs

public enum KnownAddons
{
    (...)
    ExtrasFtpShell,
    ExtrasGitShell,
    ExtrasHttpShell,
    ExtrasJsonShell,
    ExtrasMailShell,
    ExtrasRssShell,
    ExtrasSftpShell,
    ExtrasSqlShell,
    (...)
}

We've migrated all those shells to one shell pack addon, and it can be accessed through KnownAddons.AddonShellPacks.

Use KnownAddons.AddonShellPacks instead of using one of the deleted enumerations.

Display in hex "dumb mode" functions removed

IFilesystemDriver.cs

/// <summary>
/// Filesystem driver interface for drivers
/// </summary>
public interface IFilesystemDriver : IDriver
{
    void DisplayInHexDumbMode(long StartByte, long EndByte, byte[] FileByte);
    void DisplayInHexDumbMode(byte ByteContent, bool HighlightResults, long StartByte, long EndByte, byte[] FileByte);
}

BaseFilesystemDriver.cs

/// <summary>
/// Base Filesystem driver
/// </summary>
public abstract class BaseFilesystemDriver : IFilesystemDriver
{
    public virtual void DisplayInHexDumbMode(long StartByte, long EndByte, byte[] FileByte) { }
    public virtual void DisplayInHexDumbMode(byte ByteContent, bool HighlightResults, long StartByte, long EndByte, byte[] FileByte) { }
}

The base filesystem driver has recently provided the colors argument that controls whether we need to use the color VT sequences or not. This controlled the usage of colors, and we built it on top of the "dumb mode" display that is actually a better implementation of the hex display of a file.

So, we've decided to take this renderer as the candidate and replace the positioning-related code with the buffered version to take advantage of increased performance. As a result, we've merged what DisplayInHexDumbMode() functions did to their normal versions.

You'll need to use DisplayInHex() to take advantage of better performance. If you used DisplayInHex() already, there is no need to replace this function.