星火 2.0 开发文档

主题

GameSystemUI.MailSystem ​

MailAction 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public enum MailAction

邮件操作类型。

枚举值 ​

  • Query
  • MarkRead
  • Claim
  • Hide
  • ClaimAll

MailActionRequest 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public class MailActionRequest

邮件操作请求。

构造函数 ​

MailActionRequest 双端 ​

csharp
public MailActionRequest()

属性 ​

RequestId 双端 ​

csharp
public Guid RequestId { get; set; }

Action 双端 ​

csharp
public MailAction Action { get; set; }

MailKey 双端 ​

csharp
public string MailKey { get; set; }

MailActionResponse 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public class MailActionResponse

邮件操作响应。

构造函数 ​

MailActionResponse 双端 ​

csharp
public MailActionResponse()

属性 ​

RequestId 双端 ​

csharp
public Guid RequestId { get; set; }

Action 双端 ​

csharp
public MailAction Action { get; set; }

MailKey 双端 ​

csharp
public string MailKey { get; set; }

Result 双端 ​

csharp
public MailActionResult Result { get; set; }

Mail 双端 ​

csharp
public MailRecordView? Mail { get; set; }

GrantedRewards 双端 ​

csharp
public List<MailAttachmentInfo> GrantedRewards { get; set; }

UnreadCount 双端 ​

csharp
public int UnreadCount { get; set; }

UnclaimedCount 双端 ​

csharp
public int UnclaimedCount { get; set; }

MailActionResult 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public enum MailActionResult

邮件操作结果。

枚举值 ​

  • Success = 0
  • MailNotFound = 1
  • AlreadyClaimed = 2
  • AlreadyHidden = 3
  • NoAttachment = 4
  • UnparsedAttachment = 5
  • NeedClaimFirst = 6
  • Processing = 7
  • QueryFailed = 8
  • CloudDataFailed = 9
  • GrantRejected = 10
  • InvalidRequest = 11
  • ServiceNotReady = 12
  • Expired = 13
  • SystemError = 99

MailAttachmentInfo 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public class MailAttachmentInfo

邮件附件展示/发放信息。

构造函数 ​

MailAttachmentInfo 双端 ​

csharp
public MailAttachmentInfo()

属性 ​

ResourceId 双端 ​

csharp
public string ResourceId { get; set; }

资源 ID，通常对应 GameDataLobbyResource 的 Link Id。

CloudDataKey 双端 ​

csharp
public string CloudDataKey { get; set; }

云数据货币 Key。为空时由服务端按 ResourceId 反查。

DisplayName 双端 ​

csharp
public string DisplayName { get; set; }

显示名称。

IconPath 双端 ​

csharp
public string IconPath { get; set; }

图标路径。

Amount 双端 ​

csharp
public long Amount { get; set; }

数量。

CustomParams 双端 ​

csharp
public string CustomParams { get; set; }

旧库 attachment 第三段自定义参数。

MailAttachmentParser 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public static class MailAttachmentParser

运营邮件附件解析。主格式对齐旧 smallcard_mail，JSON 仅作兼容。

方法 ​

Parse 双端 ​

csharp
public static List<MailAttachmentInfo> Parse(string? rawAttachment)

兼容旧调用，按 contentType = 0 解析。

Parse 双端 ​

csharp
public static MailAttachmentParseResult Parse(int contentType, string? rawAttachment)

按后台 content_type 和 attachment 原始 payload 解析。 官方格式：content_type == 2 为星火币数量；否则为 link:count:params;link:count。

字段 ​

SparkCoinContentType 双端 ​

csharp
public const int SparkCoinContentType

旧库 content_type == 2：整段 attachment 是星火币数量。

SilentReceiveType 双端 ​

csharp
public const int SilentReceiveType

旧库 recieve_type == 1：静默邮件，登录自动领，不进收件箱 UI。

SparkCoinResourceId 双端 ​

csharp
public const string SparkCoinResourceId

星火币在旧库里的资源 link。

MailAttachmentParseResult 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public sealed class MailAttachmentParseResult

运营邮件附件解析结果。

构造函数 ​

MailAttachmentParseResult 双端 ​

csharp
public MailAttachmentParseResult()

属性 ​

Attachments 双端 ​

csharp
public List<MailAttachmentInfo> Attachments { get; init; }

UsedOfficialFormat 双端 ​

csharp
public bool UsedOfficialFormat { get; init; }

已按 smallcard_mail 官方格式解析（星火币或 link:count）。

UsedJsonFallback 双端 ​

csharp
public bool UsedJsonFallback { get; init; }

官方格式无法识别时，回退到 JSON。

IgnoredSparkCoin 双端 ​

csharp
public bool IgnoredSparkCoin { get; init; }

MailInboxQueryRequest 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public class MailInboxQueryRequest

收件箱查询请求。

构造函数 ​

MailInboxQueryRequest 双端 ​

csharp
public MailInboxQueryRequest()

属性 ​

RequestId 双端 ​

csharp
public Guid RequestId { get; set; }

MailInboxSync 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public class MailInboxSync

收件箱同步（查询响应和主动推送共用）。

构造函数 ​

MailInboxSync 双端 ​

csharp
public MailInboxSync()

属性 ​

RequestId 双端 ​

csharp
public Guid RequestId { get; set; }

Result 双端 ​

csharp
public MailActionResult Result { get; set; }

Reason 双端 ​

csharp
public MailInboxSyncReason Reason { get; set; }

Mails 双端 ​

csharp
public List<MailRecordView> Mails { get; set; }

UnreadCount 双端 ​

csharp
public int UnreadCount { get; set; }

UnclaimedCount 双端 ​

csharp
public int UnclaimedCount { get; set; }

Timestamp 双端 ​

csharp
public DateTime Timestamp { get; set; }

GrantedRewards 双端 ​

csharp
public List<MailAttachmentInfo> GrantedRewards { get; set; }

MailInboxSyncReason 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public enum MailInboxSyncReason

收件箱同步原因。

枚举值 ​

  • QueryResponse
  • LoginPush
  • StateChanged

MailRecordView 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public class MailRecordView

下发给客户端的邮件视图。

构造函数 ​

MailRecordView 双端 ​

csharp
public MailRecordView()

属性 ​

MailKey 双端 ​

csharp
public string MailKey { get; set; }

稳定邮件 Key，格式为 g:{uuid} 或 u:{uuid}。

Source 双端 ​

csharp
public MailSource Source { get; set; }

Id 双端 ​

csharp
public long Id { get; set; }

AdminEmailId 双端 ​

csharp
public long AdminEmailId { get; set; }

Uuid 双端 ​

csharp
public string Uuid { get; set; }

Title 双端 ​

csharp
public string Title { get; set; }

Content 双端 ​

csharp
public string Content { get; set; }

SenderName 双端 ​

csharp
public string SenderName { get; set; }

ContentType 双端 ​

csharp
public int ContentType { get; set; }

ReceiveType 双端 ​

csharp
public int ReceiveType { get; set; }

RawAttachment 双端 ​

csharp
public string RawAttachment { get; set; }

Attachments 双端 ​

csharp
public List<MailAttachmentInfo> Attachments { get; set; }

StartTime 双端 ​

csharp
public DateTime StartTime { get; set; }

EndTime 双端 ​

csharp
public DateTime EndTime { get; set; }

IncludeNewPlayer 双端 ​

csharp
public bool IncludeNewPlayer { get; set; }

IsRead 双端 ​

csharp
public bool IsRead { get; set; }

IsClaimed 双端 ​

csharp
public bool IsClaimed { get; set; }

IsHidden 双端 ​

csharp
public bool IsHidden { get; set; }

HasAttachment 双端 ​

csharp
public bool HasAttachment { get; set; }

CanClaim 双端 ​

csharp
public bool CanClaim { get; set; }

MailSource 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public enum MailSource

运营邮件来源。

枚举值 ​

  • Global — 全服运营邮件。
  • User — 指定玩家的个人运营邮件。

MailSystemClient 仅客户端 ​

命名空间 GameSystemUI.MailSystem

csharp
public static class MailSystemClient

邮件系统客户端。所有写操作都发给服务端，本地只缓存收件箱视图。

属性 ​

CachedMails 仅客户端 ​

csharp
public static IReadOnlyList<MailRecordView> CachedMails { get; }

当前缓存的可见邮件。

UnreadCount 仅客户端 ​

csharp
public static int UnreadCount { get; }

UnclaimedCount 仅客户端 ​

csharp
public static int UnclaimedCount { get; }

HasRedDot 仅客户端 ​

csharp
public static bool HasRedDot { get; }

IsBusy 仅客户端 ​

csharp
public static bool IsBusy { get; }

方法 ​

QueryInbox 仅客户端 ​

csharp
public static bool QueryInbox()

向服务端查询当前收件箱。

MarkRead 仅客户端 ​

csharp
public static bool MarkRead(string mailKey)

Claim 仅客户端 ​

csharp
public static bool Claim(string mailKey)

Hide 仅客户端 ​

csharp
public static bool Hide(string mailKey)

ClaimAll 仅客户端 ​

csharp
public static bool ClaimAll()

GetCachedMail 仅客户端 ​

csharp
public static MailRecordView? GetCachedMail(string mailKey)

事件 ​

OnInboxSync 仅客户端 ​

csharp
public static event EventHandler<MailInboxSync>? OnInboxSync

收件箱同步（登录推送、主动查询、状态变化都会触发）。

OnActionSuccess 仅客户端 ​

csharp
public static event EventHandler<MailActionResponse>? OnActionSuccess

邮件操作成功。

OnActionFailed 仅客户端 ​

csharp
public static event EventHandler<MailActionResponse>? OnActionFailed

邮件操作失败。

OnRedDotChanged 仅客户端 ​

csharp
public static event EventHandler<(int UnreadCount, int UnclaimedCount)>? OnRedDotChanged

红点数量变化。

MailSystemInitializer 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public class MailSystemInitializer : IGameClass

MailSystem 初始化类，负责注册邮件系统。

构造函数 ​

MailSystemInitializer 双端 ​

csharp
public MailSystemInitializer()

方法 ​

OnRegisterGameClass 双端 ​

csharp
public static void OnRegisterGameClass()

MailSystemServer 仅服务端 ​

命名空间 GameSystemUI.MailSystem

csharp
public static class MailSystemServer

邮件系统服务端：查询运营邮件、用 CloudData 保存已读/领取/隐藏，并把收件箱同步给客户端。

属性 ​

MapName 仅服务端 ​

csharp
public static string MapName { get; set; }

发布地图名。默认 Instance.ProjectId，一般不用设。

EnvironmentName 仅服务端 ​

csharp
public static string EnvironmentName { get; set; }

后台环境名。默认按当前游戏局运行环境映射：Formal→formal，Test→test，Debug→debug。

QueryCacheTtl 仅服务端 ​

csharp
public static TimeSpan QueryCacheTtl { get; set; }

运营邮件查询缓存时长。默认 0：每次都查后台。失败返回 QueryFailed，不展示、不领取。

AllowHideUnclaimed 仅服务端 ​

csharp
public static bool AllowHideUnclaimed { get; set; }

未领取附件时是否允许隐藏邮件。默认不允许。

LoginPushDelay 仅服务端 ​

csharp
public static TimeSpan LoginPushDelay { get; set; }

登录后自动推送收件箱的延迟。

EnableNewPlayerFilter 仅服务端 ​

csharp
public static bool EnableNewPlayerFilter { get; set; }

是否按 IncludeNewPlayer 过滤全服邮件。默认开启，对齐旧 smallcard_mail。 个人邮件不受影响。自定义过滤请用 ShouldIncludeMail。

ShouldIncludeMail 仅服务端 ​

csharp
public static Func<Player, User, MailRecordView, bool>? ShouldIncludeMail { get; set; }

自定义“这封邮件是否对当前玩家可见”。在内置新玩家过滤之后执行。

事件 ​

OnClaimSuccess 仅服务端 ​

csharp
public static event EventHandler<(Player Player, MailRecordView Mail, List<MailAttachmentInfo> Rewards)>? OnClaimSuccess

领取成功。

OnClaimFailed 仅服务端 ​

csharp
public static event EventHandler<(Player Player, string MailKey, MailActionResult Result)>? OnClaimFailed

领取失败。

MailTime 双端 ​

命名空间 GameSystemUI.MailSystem

csharp
public static class MailTime

邮件时间。查询、过期、剩余一律 UTC；仅 ToDisplay 转东八区给界面。

属性 ​

QueryNow 双端 ​

csharp
public static DateTime QueryNow { get; }

发给后台的查询时间。传 UTC，Kind=Utc，由 OperationMail 转成北京墙钟。

Now 双端 ​

csharp
public static DateTime Now { get; }

兼容旧调用，等同 QueryNow。

方法 ​

HasExpiryWindow 双端 ​

csharp
public static bool HasExpiryWindow(DateTime endTime)

IsExpired 双端 ​

csharp
public static bool IsExpired(DateTime endTime)

Remaining 双端 ​

csharp
public static TimeSpan Remaining(DateTime endTime)

ToUtc 双端 ​

csharp
public static DateTime ToUtc(DateTime time)

框架返回的邮件时间按 UTC。Unspecified 也按 UTC 解释。

ToDisplay 双端 ​

csharp
public static DateTime ToDisplay(DateTime time)

后台 DateTime 按 UTC 解释，转东八区展示。对齐商店订单时间。

字段 ​

BackendOffset 双端 ​

csharp
public static readonly TimeSpan BackendOffset

展示用东八区偏移。查询直接传 UTC，由框架转北京时间。