Class GameActor
An actor for ValheimCLI actions and observations. After strict VerifyEnvironment(string), it checks the expected world and plugins before every command.
public sealed class GameActor- Inheritance
-
objectGameActor
Examples
Load reviewed, strict expectations, then discover the adapter command before reading its state:
string pins = StrictExpectations.Load(pinsFile);
using var actor = new GameActor("session", new CliTransport("127.0.0.1", 5577));
actor.VerifyEnvironment(pins);
var capability = actor.RequireCapability("mymod.testing/session");
bool complete = actor.Observe(capability).Complete;The pin file comes from the test plan, not from the running game. After a world or plugin transition, verify the new expected pins and rediscover capabilities before another action. See the compiling pins example and adapter observation.
Constructors
GameActor(string, IGameTransport)
Take ownership of transport. Call VerifyEnvironment(string) before issuing a command.
public GameActor(string name, IGameTransport transport)Parameters
namestringtransportIGameTransport
Properties
BusyNote
The last busy note the game published during that wait, if any.
public string? BusyNote { get; }Property Value
- string
CommandTimeout
The timeout for each ordinary command and strict pin check; bounded world-entry reads may use less time.
public TimeSpan CommandTimeout { get; set; }Property Value
- TimeSpan
LongestMainThreadIdleMs
The largest observed frame age during a busy world-entry wait, or zero if none was observed.
public long LongestMainThreadIdleMs { get; }Property Value
- long
Name
The name used to identify this actor in diagnostics.
public string Name { get; }Property Value
- string
Methods
Dispose()
Invalidate this actor and dispose its transport. The actor does not own the game process.
public void Dispose()Execute(string, bool)
Every command rechecks strict pins. By default the reply must be accepted (RequireAccepted()):
the transport completed and the game did not refuse it. requireAccepted false permits inspecting
an expected refusal, never a pin mismatch.
public GameReply Execute(string command, bool requireAccepted = true)Parameters
commandstringrequireAcceptedbool
Returns
InvalidateEnvironment()
After an attempted world transition, require fresh explicit environment pins.
public void InvalidateEnvironment()Invoke(Capability, params string[])
Invoke a discovered extension command once and return a detached copy of its structured data.
public JsonElement Invoke(Capability command, params string[] arguments)Parameters
commandCapabilityargumentsstring[]
Returns
- JsonElement
Remarks
Each argument must be one nonempty token without whitespace. A game-side refusal, changed extension instance, or schema mismatch fails; no mutation is retried.
Observe(Capability, params string[])
Read a discovered read-only command once, preserving its source and completeness fields.
public Observation Observe(Capability command, params string[] arguments)Parameters
commandCapabilityargumentsstring[]
Returns
Exceptions
- InvalidOperationException
The capability is mutating, or its reply fails the extension contract.
ObserveComplete(Capability, string, params string[])
Observes and requires a complete observation from source.
public Observation ObserveComplete(Capability command, string source, params string[] arguments)Parameters
commandCapabilitysourcestringargumentsstring[]
Returns
ParseLine(GameReply, string)
The one structured line starting with prefix, parsed; none or several is a failure.
public static JsonDocument ParseLine(GameReply reply, string prefix)Parameters
replyGameReplyprefixstring
Returns
- JsonDocument
ParseLine(CommandResult, string)
Parse exactly one structured line in a raw transport reply. Dispose the returned document after reading it.
public static JsonDocument ParseLine(CommandResult reply, string prefix)Parameters
replyCommandResultprefixstring
Returns
- JsonDocument
RequireCapability(string, int)
Find path in the live cli_extensions listing with the exact result schema.
public Capability RequireCapability(string path, int schemaVersion = 1)Parameters
pathstringschemaVersionint
Returns
- Capability
The current extension instance and read-only flag; use it before the plugin reloads.
Exceptions
- InvalidOperationException
The extension, command or requested schema is absent, or the listing is unsupported.
SaveConfirmed()
Saves the world with cli_save and requires ValheimCLI's confirmation line (OK: SAVE ...), which it
returns. Anything else is a failure: never restart or compare persistence after an unconfirmed save.
public string SaveConfirmed()Returns
- string
VerifyEnvironment(string)
Checks the strict pins now and before every command. A transition needs this call again.
public void VerifyEnvironment(string expectationCommand)Parameters
expectationCommandstring
WaitForEnvironment(string, TimeSpan, Func<TimeSpan, CancellationToken, Task>, CancellationToken)
Wait only for an explicitly specified reload's pins; never retry a gameplay action or relax the expected set.
Checks now, then again each time changed completes. It receives the remaining time and should
await the event that follows the change, for example the reloaded plugin's load line through a LogWait:
(left, token) => log.WaitAsync(loadLine, left, cancellation: token). A failure it throws ends the wait.
public Task WaitForEnvironment(string expectations, TimeSpan timeout, Func<TimeSpan, CancellationToken, Task> changed, CancellationToken cancellation = default)Parameters
expectationsstringtimeoutTimeSpanchangedFunc<TimeSpan, CancellationToken, Task>cancellationCancellationToken
Returns
- Task
WaitForEnvironment(string, TimeSpan, CancellationToken)
Bounded fallback for a reload with no observable event: rechecks the pins every 200 ms. Prefer the overload that waits for the reload's own event.
public Task WaitForEnvironment(string expectations, TimeSpan timeout, CancellationToken cancellation = default)Parameters
expectationsstringtimeoutTimeSpancancellationCancellationToken
Returns
- Task