Interface ISceneServerSystem<TConnection>

Namespace

FishMMO.Server.Core.World.SceneServer

Assembly

FishMMO.Server.dll

Engine-agnostic public API for a Scene Server system responsible for loading and unloading scenes, tracking scene instances, and sending periodic heartbeats (pulses) to connected world servers.

public interface ISceneServerSystem<TConnection> : IServerBehaviour, IServerComponent

Type Parameters

TConnection

Remarks

Implementations must avoid exposing engine-specific types on the public surface. Methods use plain object references for connection handles so different engine/networking implementations can be supported. Thread-safety and lifetime semantics (for example when unloading during shutdown) are implementation details but should be documented by concrete implementations.

Properties

PulseRate

Pulse/heartbeat rate, in seconds. Controls how frequently the system sends status updates to world servers.

float PulseRate { get; }

Property Value

float

WorldSceneDetailsCache

Gets the world scene details cache for fast lookups of scene instance info.

WorldSceneDetailsCache WorldSceneDetailsCache { get; }

Property Value

WorldSceneDetailsCache

Methods

AdjustSceneCharacterCount(long, string, long, int)

Adjusts the tracked character count for a scene instance.

void AdjustSceneCharacterCount(long worldServerID, string sceneName, long sceneID, int amount)

Parameters

worldServerID long

World server that owns the scene instance.

sceneName string

Scene name.

sceneID long

Scene row ID identifying the instance.

amount int

Amount to adjust by.

Remarks

Exposed so the character system can keep a scene populated while it holds a combat-logout body. Those bodies are removed from the connection maps the count is otherwise derived from, so without this a scene containing only unattended bodies reports itself empty — it becomes a stale-pulse candidate for unload, and the world server sees capacity that is not really there.

CloseInstance(long, string)

Closes an instance: returns everyone inside it to the open world, then unloads it.

void CloseInstance(long sceneID, string reason)

Parameters

sceneID long

Scene row of the instance to close.

reason string

Why it is closing, for diagnostics and player messaging.

Remarks

The correct way to end an instance that still has occupants. UnloadScene(long) destroys the scene outright, which is safe only for one that is already empty — the stale sweep's case. Anything that closes an instance on the server's terms, whether a lifetime cap expiring or a party leader asking, has to go through here so the characters inside are saved, released and re-routed rather than having the ground taken from under them.

NoteDeliberateInstanceExit(long, string, long)

Records that an instance's occupant left by choice rather than by losing its connection, so an instance emptied this way is reclaimed immediately instead of being held for the idle timeout.

void NoteDeliberateInstanceExit(long worldServerID, string sceneName, long sceneID)

Parameters

worldServerID long

World server ID.

sceneName string

Instance scene name.

sceneID long

Scene row ID identifying the instance.

Remarks

Call AFTER the departure has been debited from the instance's population. See VacatedDeliberately.

TryGetInstanceExpiry(long, out DateTime)

When an instance will close on its own, if it is time-bounded.

bool TryGetInstanceExpiry(long sceneID, out DateTime expiresUtc)

Parameters

sceneID long

Scene row of the instance.

expiresUtc DateTime

When it closes, if it does.

Returns

bool

false for a scene this server does not host, an open-world scene, or one whose creation time was never recorded — none of which have an expiry to report.

Remarks

The lifetime cap is configuration this system owns, so the answer is derived here rather than by making every caller read the key and repeat the arithmetic — which is how two places end up disagreeing about when a dungeon ends.

TryGetSceneInstanceDetails(long, string, long, out ISceneInstanceDetails)

Attempts to retrieve instance details for the specified scene instance.

bool TryGetSceneInstanceDetails(long worldServerID, string sceneName, long sceneID, out ISceneInstanceDetails instanceDetails)

Parameters

worldServerID long

The id of the world server that owns the scene.

sceneName string

The canonical name of the scene.

sceneID long

The scene row ID identifying the instance. See SceneID.

instanceDetails ISceneInstanceDetails

When this method returns true, contains the instance details.

Returns

bool

true if the instance was found; otherwise false.

TryLoadSceneForConnection(TConnection, ISceneInstanceDetails)

Ensures the specified scene instance is loaded and associates the provided connection with that instance.

bool TryLoadSceneForConnection(TConnection connection, ISceneInstanceDetails instance)

Parameters

connection TConnection

An engine-agnostic connection object representing the client/peer.

instance ISceneInstanceDetails

The instance details describing which scene to load/join.

Returns

bool

true when the scene was successfully loaded/associated; otherwise false.

UnloadScene(long)

Unloads the scene with the given handle, releasing any associated resources and notifying world servers as appropriate. If the handle is unknown this method should be a no-op.

void UnloadScene(long sceneID)

Parameters

sceneID long

The scene row ID of the instance to unload.

UnloadSceneForConnection(TConnection, string)

Removes the given connection from the named scene. If the connection is the last participant the implementation may choose to unload the scene instance.

void UnloadSceneForConnection(TConnection connection, string sceneName)

Parameters

connection TConnection

The connection to remove.

sceneName string

The canonical scene name from which to remove the connection.