ServerScriptObject

This interface wraps auto-mcs’s ServerObject to expose the server configuration (including server.properties), connected players, lifecycle commands, messaging, timers, and persistent data. Access it through the global server keyword.

View the source: ServerScriptObject · ServerObject

Methods

server.launch()

Immediately starts the server if it’s not running

server.stop()

Immediately stops the server

server.restart()

Immediately stops and restarts the server

server.log(message, log_type='info')

Sends a custom log event to the console. This output is displayed only while the server is running, and is not saved to latest.log

• server.log_success(), server.log_warning(), and server.log_error() methods can also be used for automatic formatting, and only require the message parameter

Parameters	Type	Description
message*	str	The content to log
log_type	str	Accepts 'info', 'success', 'warning' or 'error'. Defaults to 'info'

server.broadcast(message, color="gray", style="italic", hyperlink=None)

Sends a custom chat message to all players and the console. This output is displayed only while the server is running, and is not saved to latest.log

• server.broadcast_success(), server.broadcast_warning(), and server.broadcast_error() methods can also be used, and only require the message parameter

Parameters	Type	Description
message*	str	The content to broadcast
color	str	Minecraft color ID, all values for /tellraw are accepted; see all color IDs
style	str	Can be 'normal', 'italic', 'bold', 'strikethrough', 'underlined', or 'obfuscated'. Defaults to 'italic'
hyperlink	str	URL to make the message a clickable hyperlink (1.7.2+)

server.operator_broadcast(message, color="gray", style="italic", hyperlink=None)

Sends a custom chat message to all operators and the console. This output is displayed only while the server is running, and is not saved to latest.log

Parameters	Type	Description
message*	str	The content to broadcast
color	str	Minecraft color ID, all values for /tellraw are accepted; see all color IDs
style	str	Can be 'normal', 'italic', 'bold', 'strikethrough', 'underlined', or 'obfuscated'. Defaults to 'italic'
hyperlink	str	URL to make the message a clickable hyperlink (1.7.2+)

server.execute(command, log=False)

Executes any Minecraft command in the server console

Note

Some commands are version dependent and you may need to implement a switch to execute different commands for different versions

Parameters	Type	Description
command*	str	Any Minecraft command; see a list of all commands
log	bool	Show EXEC line in the Console. Defaults to False

server.after(delay, function, *args, **kwargs)

Runs a delayed background (non-blocking) task. Exits before execution if the server stops, or if scripts are reloaded. Returns an instance of AmsTimer of the background task. AmsTimer.cancel() can be used to end the timer prematurely without execution

Parameters	Type	Description
delay*	int / float	Delay in seconds
function*	callable	Any Python callable function or method
args	tuple	Positional arguments passed to function
kwargs	dict	Keyword arguments passed to function

server.get_player(tag, offline=False)

Returns a matching PlayerScriptObject, or None. The special selector @a returns server.get_players()

Note

In versions prior to 1.13, tag must be a username

Parameters	Type	Description
tag*	str	Username, or a selector for a single player such as @p, @r, or @a[limit=1]; see a list of all selectors
offline	bool	Retrieves playerdata from .dat file if the target player isn’t connected to the server. Defaults to False

server.get_players()

Returns a generator of PlayerScriptObject for each online player

server._reload_scripts()

Internal method to restart the amscript engine runtime

Caution

It’s recommended to use caution when utilizing this method within a script. Restarting the engine live will remove the script context, and should be done at the very end of a method or event block

Attributes

Note

All attributes are read-only, and will not change the server data when modified

Attribute	Type	Description
server.name	str	Server’s current filename
server.version	AmsVersion	Minecraft version of the server, i.e. 1.16.3. When used in a string, it will be formatted as '1.16.3'. Can be compared with version strings
server.build	str / None	Applicable to server types with build numbers. Otherwise, None
server.type	str	Normalized server type; can be 'vanilla', 'craftbukkit', 'spigot', 'paper', 'purpur', 'forge', 'neoforge', 'fabric', or 'quilt'
server.world	str	Filename of level-name from server.properties
server.directory	str	Full path of the directory in which the server is stored
server.network	Munch	Dict-like structure containing the listening IP and port; Structured as {'ip': str, 'port': int}; can be accessed as server.network.ip and server.network.port
server.uptime	timedelta / None	Delta since launch, or None if the server has not yet started
server.is_ready	bool	True when the server’s game loop has started and is ready for players to join
server.properties	dict	Key & value pairs in the server.properties file; a boolean value for example can be accessed with server.properties['enable-command-block']
server.player_list	dict	Contains a key and a sub-dictionary for each connected player; {username: {'uuid': str, 'ip': str, 'date': datetime, 'logged-in': bool}}
server.usercache	dict	Contains a dictionary for each player who has ever joined the server; The current format is {username: uuid}
server.persistent	dict	Persistent variable storage for saving server-specific data between server restarts, or script reloads; assigning or updating a key retains it in the engine’s persistent state until changed or deleted. This data is scoped to this server, and does not persist between different servers
server.libs_path	str	Full filesystem path to amscript’s external libraries
server.util_path	str	Full filesystem path to amscript’s external binaries
server.ams_version	str	Contains the current amscript version to account for API changes
server.output	list	Contains a formatted list of dictionaries organizing the items visible in the auto-mcs console from oldest to newest (limit of 850). See the example below
server.aliases	dict	Registered @player.on_alias commands keyed by !command; includes syntax, permission, description, and source. Hidden aliases are excluded

Caution

Persistent data is saved on a normal shutdown or script reload. A crash or forced process termination may leave recent changes unwritten

Examples

server.output example:

[
    # ...earlier output omitted...

  {'text': (' 1:43:03 PM', 'INFO', 'Starting Minecraft server on *:25565', (0.6, 0.6, 1, 1))},
  {'text': (' 1:43:03 PM', 'INFO', 'Preparing level "world"', (0.6, 0.6, 1, 1))},
  {'text': (' 1:43:05 PM', 'INFO', 'Loading 0 persistent chunks...', (0.6, 0.6, 1, 1))},
  {'text': (' 1:43:05 PM', 'INFO', 'Preparing spawn area:  [/////////////////////////] 100%', (0.6, 0.6, 1, 1))},
  {'text': (' 1:43:05 PM', 'INFO', 'Time elapsed: 38 ms', (0.6, 0.6, 1, 1))},
  {'text': (' 1:43:05 PM', 'START', 'Done (1.899s)! For help, type "help". Type "!help" for auto-mcs commands', (0.3, 1, 0.6, 1))}
]

server.output[-1]['text'][2]

>>> 'Done (1.899s)! For help, type "help". Type "!help" for auto-mcs commands'