evennia.accounts.bots

Bots are a special child typeclasses of Account that are controlled by the server.

class evennia.accounts.bots.BotStarter(*args, **kwargs)

Bases: evennia.scripts.scripts.DefaultScript

This non-repeating script has the sole purpose of kicking its bot into gear when it is initialized.

at_script_creation()

Called once, when script is created.

at_server_start()

This hook is called after the server has started. It can be used to add post-startup setup for Scripts without a timer component (for which at_start could be used).

at_start()

Kick bot into gear.

at_repeat()

Called self.interval seconds to keep connection. We cannot use the IDLE command from inside the game since the system will not catch it (commands executed from the server side usually has no sessions). So we update the idle counter manually here instead. This keeps the bot getting hit by IDLE_TIMEOUT.

exception DoesNotExist

Bases: evennia.scripts.scripts.DefaultScript.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned

path = 'evennia.accounts.bots.BotStarter'

typename = 'BotStarter'

class evennia.accounts.bots.Bot(*args, **kwargs)

Bases: evennia.accounts.accounts.DefaultAccount

A Bot will start itself when the server starts (it will generally not do so on a reload - that will be handled by the normal Portal session resync)

basetype_setup()

This sets up the basic properties for the bot.

start(**kwargs)

This starts the bot, whatever that may mean.

msg(text=None, from_obj=None, session=None, options=None, **kwargs)

Evennia -> outgoing protocol

execute_cmd(raw_string, session=None)

Incoming protocol -> Evennia

at_server_shutdown()

We need to handle this case manually since the shutdown may be a reset.

exception DoesNotExist

Bases: evennia.accounts.accounts.DefaultAccount.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.accounts.accounts.DefaultAccount.MultipleObjectsReturned

path = 'evennia.accounts.bots.Bot'

typename = 'Bot'

class evennia.accounts.bots.IRCBot(*args, **kwargs)

Bases: evennia.accounts.bots.Bot

Bot for handling IRC connections.

factory_path = 'evennia.server.portal.irc.IRCBotFactory'

start(ev_channel=None, irc_botname=None, irc_channel=None, irc_network=None, irc_port=None, irc_ssl=None)

Start by telling the portal to start a new session.

Parameters

• ev_channel (str) – Key of the Evennia channel to connect to.

• irc_botname (str) – Name of bot to connect to irc channel. If not set, use self.key.

• irc_channel (str) – Name of channel on the form #channelname.

• irc_network (str) – URL of the IRC network, like irc.freenode.net.

• irc_port (str) – Port number of the irc network, like 6667.

• irc_ssl (bool) – Indicates whether to use SSL connection.

at_msg_send(**kwargs)

Shortcut here or we can end up in infinite loop

get_nicklist(caller)

Retrive the nick list from the connected channel.

Parameters

caller (Object or Account) – The requester of the list. This will be stored and echoed to when the irc network replies with the requested info.

Notes: Since the return is asynchronous, the caller is stored internally

in a list; all callers in this list will get the nick info once it returns (it is a custom OOB inputfunc option). The callback will not survive a reload (which should be fine, it’s very quick).

ping(caller)

Fire a ping to the IRC server.

Parameters

caller (Object or Account) – The requester of the ping.

reconnect()

Force a protocol-side reconnect of the client without having to destroy/recreate the bot “account”.

msg(text=None, **kwargs)

Takes text from connected channel (only).

Parameters

text (str, optional) – Incoming text from channel.

Keyword Arguments

options (dict) – Options dict with the following allowed keys: - from_channel (str): dbid of a channel this text originated from. - from_obj (list): list of objects sending this text.

execute_cmd(session=None, txt=None, **kwargs)

Take incoming data and send it to connected channel. This is triggered by the bot_data_in Inputfunc.

Parameters

• session (Session, optional) – Session responsible for this command. Note that this is the bot.

• txt (str, optional) – Command string.

Keyword Arguments

• user (str) – The name of the user who sent the message.

• channel (str) – The name of channel the message was sent to.

• type (str) – Nature of message. Either ‘msg’, ‘action’, ‘nicklist’ or ‘ping’.

• nicklist (list, optional) – Set if type=’nicklist’. This is a list of nicks returned by calling the self.get_nicklist. It must look for a list self._nicklist_callers which will contain all callers waiting for the nicklist.

• timings (float, optional) – Set if type=’ping’. This is the return (in seconds) of a ping request triggered with self.ping. The return must look for a list self._ping_callers which will contain all callers waiting for the ping return.

exception DoesNotExist

Bases: evennia.accounts.bots.Bot.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.accounts.bots.Bot.MultipleObjectsReturned

path = 'evennia.accounts.bots.IRCBot'

typename = 'IRCBot'

class evennia.accounts.bots.RSSBot(*args, **kwargs)

Bases: evennia.accounts.bots.Bot

An RSS relayer. The RSS protocol itself runs a ticker to update its feed at regular intervals.

start(ev_channel=None, rss_url=None, rss_rate=None)

Start by telling the portal to start a new RSS session

Parameters

• ev_channel (str) – Key of the Evennia channel to connect to.

• rss_url (str) – Full URL to the RSS feed to subscribe to.

• rss_rate (int) – How often for the feedreader to update.

Raises

RuntimeError – If ev_channel does not exist.

execute_cmd(txt=None, session=None, **kwargs)

Take incoming data and send it to connected channel. This is triggered by the bot_data_in Inputfunc.

Parameters

• session (Session, optional) – Session responsible for this command.

• txt (str, optional) – Command string.

• kwargs (dict, optional) – Additional Information passed from bot. Not used by the RSSbot by default.

exception DoesNotExist

Bases: evennia.accounts.bots.Bot.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.accounts.bots.Bot.MultipleObjectsReturned

path = 'evennia.accounts.bots.RSSBot'

typename = 'RSSBot'

class evennia.accounts.bots.GrapevineBot(*args, **kwargs)

Bases: evennia.accounts.bots.Bot

g Grapevine (https://grapevine.haus) relayer. The channel to connect to is the first name in the settings.GRAPEVINE_CHANNELS list.

factory_path = 'evennia.server.portal.grapevine.RestartingWebsocketServerFactory'

start(ev_channel=None, grapevine_channel=None)

Start by telling the portal to connect to the grapevine network.

at_msg_send(**kwargs)

Shortcut here or we can end up in infinite loop

msg(text=None, **kwargs)

Takes text from connected channel (only).

Parameters

text (str, optional) – Incoming text from channel.

Keyword Arguments

options (dict) – Options dict with the following allowed keys: - from_channel (str): dbid of a channel this text originated from. - from_obj (list): list of objects sending this text.

execute_cmd(txt=None, session=None, event=None, grapevine_channel=None, sender=None, game=None, **kwargs)

Take incoming data from protocol and send it to connected channel. This is triggered by the bot_data_in Inputfunc.

exception DoesNotExist

Bases: evennia.accounts.bots.Bot.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.accounts.bots.Bot.MultipleObjectsReturned

path = 'evennia.accounts.bots.GrapevineBot'

typename = 'GrapevineBot'

class evennia.accounts.bots.DiscordBot(*args, **kwargs)

Bases: evennia.accounts.bots.Bot

Discord bot relay. You will need to set up your own bot (https://discord.com/developers/applications) and add the bot token as DISCORD_BOT_TOKEN to secret_settings.py to use

factory_path = 'evennia.server.portal.discord.DiscordWebsocketServerFactory'

at_init()

Load required channels back into memory

start()

Tell the Discord protocol to connect.

at_pre_channel_msg(message, channel, senders=None, **kwargs)

Called by the Channel just before passing a message into channel_msg.

We overload this to set the channel tag prefix.

channel_msg(message, channel, senders=None, relayed=False, **kwargs)

Passes channel messages received on to discord

Parameters

• message (str) –

• channel (Channel) –

Keyword Arguments

• senders (list or None) - Object(s) –

• relayed (bool) –

change_nickname(new_nickname, guild_id, user_id, **kwargs)

Changes a given user’s nickname on the given guild the bot is in.

Parameters

• new_nickname (str) –

• guild_id (int) –

• user_id (int) –

assign_role(role_id, guild_id, user_id, **kwargs)

Assigns a user the role on the given guild the bot is in.

Parameters

• role_id (int) –

• guild_id (int) –

• user_id (int) –

direct_msg(message, sender, **kwargs)

Called when the Discord bot receives a direct message on Discord.

Parameters

• message (str) –

• sender (tuple) - The Discord info for the sender in the form (id, nickname) –

Keyword Arguments

**kwargs (optional) –

relay_to_channel(message, to_channel, sender=None, from_channel=None, from_server=None, **kwargs)

Formats and sends a Discord -> Evennia message. Called when the Discord bot receives a channel message on Discord.

Parameters

• message (str) –

• to_channel (Channel) –

Keyword Arguments

• sender (tuple) - The Discord info for the sender in the form **(id, nickname) –

• from_channel (str) –

• from_server (str) –

• - Any additional keywords. Unused by default, but available for adding additional (kwargs) – flags or parameters.

execute_cmd(txt=None, session=None, type=None, sender=None, **kwargs)

Take incoming data from protocol and send it to connected channel. This is triggered by the bot_data_in Inputfunc.

Keyword Arguments

• txt (str) –

• session (Session) –

• type (str, optional) – the protocol pre-processed it.

• sender (tuple) – strings, in the form of (id, nickname)

• - Any additional data specific to a particular type of actions. The data for (kwargs) – any Discord actions not pre-processed by the protocol will also be passed via kwargs.

exception DoesNotExist

Bases: evennia.accounts.bots.Bot.DoesNotExist

exception MultipleObjectsReturned

Bases: evennia.accounts.bots.Bot.MultipleObjectsReturned

path = 'evennia.accounts.bots.DiscordBot'

typename = 'DiscordBot'