What's New in Dalamud v16
This version is not finalized, and all details here are subject to change.
Dalamud v16 is the next major version of Dalamud, currently in development, and
will release with Patch 8.0.
This is a high-level overview of changes. You can see a code diff of all of
these changes
here.
Key Information​
- Branch:
api16(view on GitHub) - Release Date: TBA
- API Level: 16
- .NET Version: .NET 10.0.0 (to be upgraded to .NET 11 when it releases)
Major Changes​
Upgrade to .NET 11 / C# 15 (Pending)​
Please refer to the official documentation for more information:
SeString and Payload classes removed​
The mutable SeString class and its associated Payload classes have been
removed. All Dalamud APIs now use the immutable ReadOnlySeString or
ReadOnlySeStringSpan structs from Lumina to improve memory efficiency and to
provide a modern implementation that propertly supports the type.
Because ReadOnlySeString is immutable, its contents cannot be modified
directly. To alter an existing string, instantiate a SeStringBuilder, iterate
through the payloads of the original string, and append or modify the payloads
as needed to produce a new ReadOnlySeString.
To eliminate unnecessary heap allocations please rent a pooled SeStringBuilder
instance using
RentedSeStringBuilder,
which automatically returns to the shared ObjectPool when disposed.
Example: Modifying Chat Messages
The following example demonstrates how to intercept a chat message, search for a
target text sequence ("Dalamud"), and wrap it in color macros using
RentedSeStringBuilder:
public class ExampleChatHandlerClass : IDisposable
{
private readonly IChatGui _chatGui;
public ExampleChatHandlerClass(IChatGui chatGui)
{
_chatGui = chatGui;
_chatGui.ChatMessage += OnChatMessage;
}
public void Dispose()
{
_chatGui.ChatMessage -= OnChatMessage;
}
private void OnChatMessage(IHandleableChatMessage message)
{
// Skip processing if the message does not contain the target text
if (!message.Message.ContainsText("Dalamud"u8))
return;
using var rssb = new RentedSeStringBuilder();
foreach (var payload in message.Message)
{
if (payload.Type == ReadOnlySePayloadType.Text && payload.Body.Span.IndexOf("Dalamud"u8) is var pos && pos != -1)
{
// Append text before Dalamud
rssb.Append(payload.Body.Span[..pos]);
// Append Dalamud wrapped in color macros
rssb.PushEdgeColorType(701)
.PushColorType(539)
.Append("Dalamud"u8)
.PopColorType()
.PopEdgeColorType();
// Append text after Dalamud
rssb.Append(payload.Body.Span[(pos + "Dalamud"u8.Length)..]);
}
else
{
// Append every other payload as-is
rssb.Append(payload);
}
}
// Set the new message
message.Message = rssb.ToReadOnlySeString();
}
}
Example: Extracting Item Link Details from a Chat Messages
The following example demonstrates how to inspect a chat message to extract an item ID from an item link:
public class ExampleChatHandlerClass : IDisposable
{
private readonly IChatGui _chatGui;
private readonly IPluginLog _pluginLog;
public ExampleChatHandlerClass(IChatGui chatGui, IPluginLog pluginLog)
{
_chatGui = chatGui;
_pluginLog = pluginLog;
_chatGui.ChatMessage += OnChatMessage;
}
public void Dispose()
{
_chatGui.ChatMessage -= OnChatMessage;
}
private void OnChatMessage(IHandleableChatMessage message)
{
foreach (var payload in message.Message)
{
if (!payload.IsLink(LinkMacroPayloadType.Item))
continue;
if (!payload.TryGetExpression(out _, out var eItemId))
continue;
// Chat messages do not contain placeholder, parameter or binary expressions,
// so reading the raw value here is perfectly fine.
if (!eItemId.TryGetUInt(out var itemId))
continue;
var (baseItemId, itemKind) = ItemUtil.GetBaseId(itemId);
_pluginLog.Debug("Found Item#{itemId} as {itemKind}", baseItemId, itemKind);
break;
}
}
}
For more information read Migrating to ReadOnlySeString.
For a deeper dive into SeString structure and macros, please have a look at our SeString documentation.
Dalamud.Excel.Sheets​
Instead of providing sheets through the Lumina.Excel.Sheets namespace, Dalamud
now provides them through its own namespace Dalamud.Excel.Sheets.
Reason: The Lumina.Excel.Sheets namespace was generated from an EXDSchema
commit pinned at the start of a major game patch. To provide a stable API for
Dalamud and its plugins, sheet definitions were not updated even when a minor
game patch introduced column changes, rendering affected sheets unusable until
the next major API bump.
To prevent this, Dalamud and Lumina.Excel now operate independently:
Dalamud.Excel.Sheetsmaintains API stability until a major release, while allowing us to fix column definitions whenever they are needed.Lumina.Excelhas dropped theLumina.Excel.Sheets.Experimentalnamespace to make it the new default and now publishes NuGet updates more frequently with sheets generated from the latest EXDSchema.
This change also allows plugin developers to add the Lumina.Excel package as
PackageReference whenever they want full control over sheet updates.
New Features​
Changes to existing features​
IClientState​
- The
CfPopevent now fires on the Framework thread instead of insideTask.Run. Plugins performing long-running operations, like network requests, should wrap their logic in aTask.Runcall to avoid blocking the main thread.
Minor Changes​
- The
Onprefix was removed from event names and delegates. - Events using
EventHandler<T>were changed toAction<T>, dropping thesenderarg. - Properties and events in
IClientStatenow use the appropiateRowRef<T>type, instead of using the RowId.
Important: Please make sure to compare theRowIdproperty now, not theRowRef<T>itself. IGameGui.HoveredItemand its eventHoveredItemChangednow correctly useuintinstead ofulongfor the Item Id.- MinHook was removed during API 15, so the
HookBackendparameter has now been removed from allIGameInteropProviderfunctions. - FASM support was removed during API 15, so the
string[]overload of the AsmHook constructor has now been removed. - Added the
MapCoordinateandWorldCoordinatestructs to help with converting between the coordinate systems and providing a better defined API for map links.MapUtil.GetMapCoordinates(IGameObject, bool)was removed in favor of the newIGameObject.GetMapCoordinate()andIGameObject.GetWorldCoordinate()functions.- New extension functions
ToWorldCoordinate()andToMapCoordinate()were added for theLevelsheet. IGameGui.OpenMapWithMapLinkwas changed to accept both of the mentioned structs.- See also: Migrating to ReadOnlySeString - Map links.
Namespace Changes​
Lumina.Excel.Sheets→Dalamud.Excel.Sheets, unless you use the Lumina.Excel NuGet package.Dalamud.Game.Network.Structures→Dalamud.Game.Marketboard.Network.StructuresDalamud.Game.ClientLanguagewas moved toDalamud.Common.ClientLanguage.IDragDropManagerandIDalamudAssetManagerhave been moved into theDalamud.Plugin.Servicesnamespace.
SDK Changes​
- The PackageReferences
DalamudPackagerandDotNet.ReproducibleBuildsare now defined implicitly, so their version is controlled by the SDK. Please remove them from your plugins .csproj file. - The
RuntimeIdentifieris now set to only target thewin-x64platform by default. - Added the option to opt-in to outdated SDK warnings after builds by setting
<Warn_Outdated_Sdk>true</Warn_Outdated_Sdk>. - Added a reference to the
Dalamud.Commonassembly. - Replaced the
Lumina.Excelreference withDalamud.Excel.Sheets. - Renamed the
Use_Dalamud_Lumina_Excelproperty toUse_Dalamud_Excel_Sheets.