Interface INetworkAutomation

Namespace

AcDream.Plugin.Abstractions

Assembly

AcDream.Plugin.Abstractions.dll

Seeing the other clients this computer is running. Each client publishes its own character periodically and reads what the others published; nothing is sent to the game server and nothing leaves the machine.

public interface INetworkAutomation

Remarks

The host itself never talks to another computer. A plugin that has a transport of its own can carry the same information further: it reads what this client tells its neighbours with TryCaptureSelf(out PluginNetworkClient), CaptureOwnCasts(long) and CaptureOwnCommands(long), sends that wherever it likes, and hands what comes back to ImportRemoteClient(PluginNetworkClient), ImportRemoteCast(uint, uint, uint, int, double, bool) and ImportRemoteCommand(uint, string, IReadOnlyList<string>, int). What it imports then appears in CaptureClients(), CaptureCasts(long) and CaptureCommands(long) marked as remote, under the same rules as a client on this computer: the same fifteen-second staleness, the same world and label filtering, and an imported command line is run by this client exactly as a line from a neighbour is. Imports stay in this client; they are not passed on to the other clients on this computer.

Properties

IsAvailable

True when this host publishes and reads peer state. The default implementation always reports false.

bool IsAvailable { get; }

Property Value

bool

IsConnected

Whether a subscribed local peer connection is currently established. False means capture results may be incomplete while connection is pending or unavailable.

bool IsConnected { get; }

Property Value

bool

SupportsSubscriptions

True when this host supports explicit peer subscriptions.

bool SupportsSubscriptions { get; }

Property Value

bool

Methods

AnnounceCastAttempt(uint, uint, int)

Tells the other clients on this computer that this character has begun casting a spell at something, before it is known whether it lands. Use it so a second character can decide not to start the same spell at the same target; it says nothing about an effect being in place, which is what AnnounceCastSuccess(uint, uint, int, double) is for.

bool AnnounceCastAttempt(uint targetObjectId, uint spellId, int effectiveSkill)

Parameters

targetObjectId uint

The object being cast at.

spellId uint

The spell, which must be one this client's own spell table knows.

effectiveSkill int

The magic skill the character is casting with, or zero to say nothing about it. A negative number is refused.

Returns

bool

False for a zero target, a spell this client's spell table does not know, a negative skill, a character that is not in the world, or a host that does not tell other clients anything -- which is what the default implementation does.

AnnounceCastSuccess(uint, uint, int, double)

Tells the other clients on this computer that a spell this character cast has landed and how long its effect lasts, so another character can stand down rather than re-landing it.

bool AnnounceCastSuccess(uint targetObjectId, uint spellId, int effectiveSkill, double durationSeconds)

Parameters

targetObjectId uint

The object it landed on.

spellId uint

The spell, which must be one this client's own spell table knows.

effectiveSkill int

The magic skill it was cast with, or zero to say nothing about it.

durationSeconds double

How long the effect lasts in total, from now. A reader is handed what is left of it rather than this number.

Returns

bool

False for a zero target, a spell this client's spell table does not know, a negative skill, a duration that is not a finite positive number of seconds or is longer than a day, a character that is not in the world, or a host that does not tell other clients anything -- which is what the default implementation does.

BroadcastCommand(string, IReadOnlyList<string>, int)

Asks the other clients on this computer to run a line, as though the player had typed it into the chat entry there. It is the one free-form channel between clients: the receiving client submits the line through its own chat entry, so its own commands are consulted first, then the plugins' chat interceptors, then the verbs plugins and the client have registered, and anything left goes to a channel, a tell or the server exactly as typed speech does.

bool BroadcastCommand(string line, IReadOnlyList<string> tags, int delayMilliseconds)

Parameters

line string

The line, written exactly as it would be typed. It may be a plugin verb, one of the client's own commands, a server command or something to say; a line nothing claims is answered on the receiving client the way an unknown command typed there is answered.

tags IReadOnlyList<string>

The labels to aim it at. Only a client whose own labels include one of these runs it. An empty or null list aims it at every client on this computer that is playing in the same world.

delayMilliseconds int

How far apart the recipients run it. Every client that takes the line orders itself against the others by client id, with the sender first, and waits its own place in that order times this many milliseconds before running it -- so the first recipient waits one delay, the second two, and so on. Zero has them all run it as soon as they read it.

Returns

bool

False for an empty line, a line longer than 512 characters or carrying a control character, more than 16 labels or one longer than 64 characters, a delay below zero or above sixty seconds, a character that is not in the world, or a host that tells other clients nothing -- which is what the default implementation does.

Remarks

The sending client does not run its own line: it already knows what it asked for, and a plugin that wants the line run here as well runs it here itself.

CaptureCasts(long)

What the other clients on this computer have said they cast. Nothing is applied to this client's own bookkeeping by reading it: what to do with a peer's cast is the plugin's decision, and a plugin that wants a landed one counted as an effect in place passes it to ReportCast(uint, uint, double) with SecondsRemaining as the duration.

IReadOnlyList<PluginPeerCast> CaptureCasts(long afterSequence)

Parameters

afterSequence long

The highest Sequence already dealt with, or zero for everything still recent. Hand back the highest sequence from one call to the next and each cast arrives once.

Returns

IReadOnlyList<PluginPeerCast>

The casts above that sequence, oldest first, never including this character's own and never including a spell this client's own spell table cannot identify. Empty when there is nothing new, when no other client on this computer is playing in the same world, or on a host that does not read other clients -- which is what the default implementation returns.

CaptureClients()

The other clients on this computer, never including the caller's own.

IReadOnlyList<PluginNetworkClient> CaptureClients()

Returns

IReadOnlyList<PluginNetworkClient>

One entry per peer whose published state is still recent and well formed; an empty list when there are no such peers or the host does not support peers, which is what the default implementation returns.

CaptureCommands(long)

What the other clients on this computer have asked the clients around them to run. Reading them changes nothing: the client runs the lines meant for it by itself, and this is for a plugin that wants to see what was asked for, or to act on a line rather than leave it to a verb.

IReadOnlyList<PluginPeerCommand> CaptureCommands(long afterSequence)

Parameters

afterSequence long

The highest Sequence already dealt with, or zero for everything still recent. Hand back the highest sequence from one call to the next and each line arrives once.

Returns

IReadOnlyList<PluginPeerCommand>

The lines above that sequence, oldest first, never including this client's own and never including one aimed at labels this client does not answer to. Empty when there is nothing new, when no other client on this computer is playing in the same world, or on a host that does not read other clients -- which is what the default implementation returns.

CaptureOwnCasts(long)

The casts this client itself announced through AnnounceCastAttempt(uint, uint, int) and AnnounceCastSuccess(uint, uint, int, double) that are still within the fifteen seconds a neighbour would take them in, so a plugin can pass them on to clients this computer cannot reach.

IReadOnlyList<PluginPeerCast> CaptureOwnCasts(long afterSequence)

Parameters

afterSequence long

The highest Sequence already dealt with, or zero for everything still recent. The sequence here is this client's own count of its announcements, which is not the numbering CaptureCasts(long) uses.

Returns

IReadOnlyList<PluginPeerCast>

The announcements above that sequence, oldest first, each carrying this client's own ClientId and character as the caster. SecondsRemaining is what is left of an announced success's duration, in seconds, and zero for an attempt. At most the last thirty-two announcements are kept, and they are dropped when the character leaves the world. Empty when there is nothing new or on a host that tells other clients nothing -- which is what the default implementation returns.

CaptureOwnCommands(long)

The lines this client itself asked its neighbours to run through BroadcastCommand(string, IReadOnlyList<string>, int) that are still within the fifteen seconds a neighbour would take them in, so a plugin can pass them on to clients this computer cannot reach.

IReadOnlyList<PluginPeerCommand> CaptureOwnCommands(long afterSequence)

Parameters

afterSequence long

The highest Sequence already dealt with, or zero for everything still recent. The sequence here is this client's own count of its broadcasts.

Returns

IReadOnlyList<PluginPeerCommand>

The broadcasts above that sequence, oldest first, each carrying this client's own ClientId and character as the sender and the labels it was aimed at. At most the last thirty-two are kept, and they are dropped when the character leaves the world. Empty when there is nothing new or on a host that tells other clients nothing -- which is what the default implementation returns.

ImportRemoteCast(uint, uint, uint, int, double, bool)

Adds a cast a remote peer said it made, so it appears in CaptureCasts(long) with IsRemote true, under the same rules as a cast read from a client on this computer: it is only handed out while the caster plays in this client's world, and only for fifteen seconds after the import.

bool ImportRemoteCast(uint casterObjectId, uint targetObjectId, uint spellId, int effectiveSkill, double secondsRemaining, bool landed)

Parameters

casterObjectId uint

The casting character, which must be a peer imported through ImportRemoteClient(PluginNetworkClient) within the last fifteen seconds.

targetObjectId uint

The object it was cast at.

spellId uint

The spell, which must be one this client's own spell table knows.

effectiveSkill int

The magic skill it was cast with, or zero when the caster did not say.

secondsRemaining double

For a landed cast, how many seconds of the effect are left at the moment of the import; a reader is handed what is left of this as time passes. Ignored for an attempt.

landed bool

True for a cast the caster said landed, false for an attempt that may still fizzle or be resisted.

Returns

bool

False for a caster that is not a recently imported peer, a zero target, a spell this client's spell table does not know, a negative skill, a landed cast whose remaining time is not a finite positive number of seconds or is longer than a day, a character here that is not in the world, or a host that reads no peers -- which is what the default implementation does.

ImportRemoteClient(PluginNetworkClient)

Adds or refreshes a peer this client cannot see on this computer -- typically a character on another computer whose state a plugin carried here -- so it appears in CaptureClients() beside the local ones, with IsRemote true.

bool ImportRemoteClient(PluginNetworkClient client)

Parameters

client PluginNetworkClient

The peer as the other client described itself, keyed by PlayerId: importing the same player again replaces what was imported before. Its ClientId and IsRemote are ignored: this client gives each imported player a client id of its own, stable for as long as the player keeps being imported.

Returns

bool

False for a zero player id, this client's own character, a blank name or one longer than 128 characters, a world name longer than 128 characters, a label longer than 64 characters or more than 128 of them, a position or heading that is not a finite number, a 257th remote peer while 256 are still recent, a character here that is not in the world, or a host that reads no peers -- which is what the default implementation does.

Remarks

An imported peer is stamped with this client's clock when it is imported and drops out of CaptureClients() fifteen seconds after the last import, exactly as a neighbour that stops writing its note does, so a plugin keeps importing a peer as long as it hears from it. A player this client already sees on this computer, in the same world, is read from there, and what is imported for it while the local note is recent is passed over for good, so a relay that echoes a neighbour back never delivers its casts or lines twice. The player id is the only key, and the server numbers players per world: two remote characters of different worlds that share an id are one peer here, and one whose id is this client's own is refused.

ImportRemoteCommand(uint, string, IReadOnlyList<string>, int)

Adds a line a remote peer asked the clients around it to run. This client treats it exactly as a line broadcast by a client on this computer: when it is aimed at labels this client answers to, the client runs it through its own chat entry after its place in the recipients' order, and it appears in CaptureCommands(long) with IsRemote true.

bool ImportRemoteCommand(uint senderObjectId, string line, IReadOnlyList<string> tags, int delayMilliseconds)

Parameters

senderObjectId uint

The sending character, which must be a peer imported through ImportRemoteClient(PluginNetworkClient) within the last fifteen seconds. A line from a peer playing in another world is accepted and never run.

line string

The command line, as the sender wrote it.

tags IReadOnlyList<string>

The labels the sender aimed it at; an empty or null list aims it at every client.

delayMilliseconds int

The stagger the sender asked for, in milliseconds per place in the recipients' order, as in BroadcastCommand(string, IReadOnlyList<string>, int).

Returns

bool

False for a sender that is not a recently imported peer, and for everything BroadcastCommand(string, IReadOnlyList<string>, int) refuses: an empty line, a line longer than 512 characters or carrying a control character, more than 16 labels or one longer than 64 characters, a delay below zero or above sixty seconds, a character here that is not in the world, or a host that reads no peers -- which is what the default implementation does.

Remarks

The line is run as if this client's player had typed it: client commands, other plugins' verbs, tells and whatever the server accepts from this character, admin commands included. The host checks only that the sender was imported recently, which the relay also controls. Authenticate the transport and import lines only from senders you trust; a relay that cannot vouch for its peers should import their state and casts and leave their lines out.

SetTags(IReadOnlyList<string>)

Sets the labels this client answers to, replacing whatever it was started with. The labels go in the note the other clients read, so they see this client under them, and they decide which broadcast command lines this client runs.

bool SetTags(IReadOnlyList<string> tags)

Parameters

tags IReadOnlyList<string>

The labels. They are trimmed, empty ones are dropped, repeats ignoring case are folded together, and what is left is capped at 128. An empty list clears them, which leaves this client answering only to broadcasts aimed at everybody.

Returns

bool

False for a null list, a label longer than 64 characters, or a host that tells other clients nothing -- which is what the default implementation does.

Subscribe(PluginPeerCapabilities)

Participates in the selected peer features until the returned lease is disposed. Several plugins share one connection. No leases means no peer transport work. Older hosts return null and retain their existing behavior.

IDisposable? Subscribe(PluginPeerCapabilities capabilities)

Parameters

capabilities PluginPeerCapabilities

The features this plugin needs on this client.

Returns

IDisposable

A lease, or null for unsupported or invalid capabilities.

TryCaptureSelf(out PluginNetworkClient)

What this client is telling the other clients on this computer about its own character right now: the same record they read back through their CaptureClients(), built on demand rather than read from the note, so it is current even between two writes of the note.

bool TryCaptureSelf(out PluginNetworkClient self)

Parameters

self PluginNetworkClient

This client's own entry, with its own ClientId and IsRemote false; the default value when this returns false.

Returns

bool

False when the character is not in the world, when its position is not known yet, or on a host that tells other clients nothing -- which is what the default implementation does.