User:Moonmoon/config

From Werewolf Wiki
Jump to navigation Jump to search

Bot configuration is performed in the botconfig.yml file. A sample file is provided, you should copy it to botconfig.yml and modify it as needed. Follow the instructions in that file for more information, and make sure to use spaces (not tabs) for any indentation.

Below is a listing of every valid parameter that can be configured, starting from the top-level ("root"). The configuration file is validated for the names of parameters and data types of values, and the bot will not run with an invalid configuration file.

root

Top-level configuration object

Default Value:

access: (see access)
debug: (see debug)
gameplay: (see gameplay)
logging: (see logging)
ratelimits: (see ratelimits)
reaper: (see reaper)
ssl: (see ssl)
telemetry: (see telemetry)
timers: (see timers)
transports: (see transports)
warnings: (see warnings)

root.access

Instance of access.

root.debug

Instance of debug.

root.gameplay

Instance of gameplay.

root.logging

Instance of logging.

root.ratelimits

Instance of ratelimits.

root.reaper

Instance of reaper.

root.ssl

Instance of ssl.

root.telemetry

Instance of telemetry.

root.timers

Instance of timers.

root.transports

Instance of transports.

root.warnings

Instance of warnings.

access

The access section defines shorthand notation "templates" for collections of flags as well as allows you to define a list of accounts who have access to the bot. In addition to this section, access can be granted to accounts via the fflags command. Access granted via the command is stored in the database rather than the configuration file, and the command is unable to modify or delete entries present in the file.

Default Value:

entries: []
templates:
- name: owner
  flags: AaDdFfgjmNpSsw
- name: admin
  flags: AaDdfgjmNpSsw
- name: moderator
  flags: AadgjmNpSsw

access.entries

List of accounts with access to the bot.

Default Value: (empty list)

access.templates

Templates are a way to associate a friendly name with a collection of flags. By default, three templates are defined:

  • owner: full access to the bot and can execute every command
  • admin: access to manage moderators and execute commands which can update the bot's code or cause it to restart
  • moderator: manage games in progress and warn users, but cannot manage access entries or cause the bot to restart

Default Value:

- name: owner
  flags: AaDdFfgjmNpSsw
- name: admin
  flags: AaDdfgjmNpSsw
- name: moderator
  flags: AadgjmNpSsw

access.entry

An access entry associates an account on a given transport with an access template. Unlike the fflags command, access entries in the configuration file must be associated with a template, and cannot be a freeform collection of flags.

Default Value:

account:
template:
transport:

access.entry.account

Account name being granted access.

Default Value: (none)

access.entry.template

Access template to grant to the account.

Default Value: (none)

access.entry.transport

Transport name that the account being granted access is on.

Default Value: (none)

access.template

A template associates a friendly name with a collection of flags.

Default Value:

flags:
name:

access.template.flags

Flags that this template grants. For readability, it is recommended to list them in alphabetical order.

Default Value: (none)

access.template.name

Name of the template, must be unique.

Default Value: (none)

connection

Connections represent networks that the bot will connect to in the outbound direction.

Default Value:

host:
port:
source: ''
ssl:
  use_ssl: true
  verify_peer: true
  trusted_fingerprints: []

connection.host

Hostname or IP address to connect to.

Default Value: (none)

connection.port

Port number to connect to.

Default Value: (none)

connection.source

IP address to use as our source IP for the outbound connection. If the empty string, uses the default logic of the OS to determine source IP.

Default Value: ""

connection.ssl

Settings controlling whether or not encrypted connections are used, and server-specific options for encrypted connections.

Default Value:

trusted_fingerprints: []
use_ssl: true
verify_peer: true

connection.ssl.trusted_fingerprints

List of trusted server fingerprints. If the server certificate does not chain to a trusted CA, it is preferable to configure the fingerprints here rather than disabling verification. Fingerprints must be hashed with SHA-256. If configured, it will look like so:

trusted_fingerprints:
  - 74:51:AD:BF:59:B2:47:76:A8:64:97:E8:82:6B:A5:99:C9:CB:E1:64:F5:F2:B4:84:2A:9B:F7:F4:88:21:88:3F

To obtain a fingerprint, run the following command, replacing "irc.libera.chat:6697" with correct values for your host and port number.

openssl s_client -connect irc.libera.chat:6697 < /dev/null 2>/dev/null | openssl x509 -fingerprint -sha256 -noout -in /dev/stdin

Default Value: (empty list)

connection.ssl.use_ssl

Whether or not to use encrypted connections when connecting to the server.

Default Value: true

connection.ssl.verify_peer

If set, try to verify the server certificate of the remote side to ensure it is valid and chains to a trusted Certificate Authority (CA). Certificates whose fingerprints are listed in trusted_fingerprints will also verify successfully even if they don't chain to a trusted CA so long as they pass all other validation checks (e.g. not revoked or expired). Disabling this can have disastrous consequences.

Default Value: true

debug

This section defines special handling that aids in debugging the bot. Debug mode should not be enabled during the course of normal bot operation.

Default Value:

containers:
  names: []
  limit: 50
enabled: false
gameplay:
  timelord: true
messages:
  nothrow: false

debug.containers

Options related to debugging various internal containers (CheckedDict, CheckedList, CheckedSet)

Default Value:

limit: 50
names: []

debug.containers.limit

Max number of history entries to store per container

Default Value: 50

debug.containers.names

Container names to enable debug history for

Default Value: (empty list)

debug.enabled

Whether or not debug mode is enabled. This will enable a variety of commands that aid in debugging. If disabled, none of the other options in this section have any effect.

Default Value: false

debug.gameplay

Options related to playing games while in debug mode

Default Value:

timelord: true

debug.gameplay.timelord

Whether or not time lord will reduce timers when they die. If false, we still play the message and otherwise pretend that timers were reduced, but do not actually modify the timers.

Default Value: true

debug.messages

Options related to debugging the messages system

Default Value:

nothrow: false

debug.messages.nothrow

If true, most errors in the messages system will be sent to the client instead of causing the bot to log an error and interrupt execution of the current routine. If working on translations, it is recommended to enable this at first while ironing out the bulk of issues, then leave it disabled while performing final testing.

Default Value: false

gameplay

The gameplay section is used to configure settings related to gameplay.

Default Value:

deadchat: true
disable:
  roles: []
  gamemodes: []
  commands: []
gunner_wolf:
  kills_attacker: 25
  steals_gun: true
hidden:
  traitor: true
  amnesiac: false
  clone: false
language: en
nightchat: true
player_limits:
  minimum: 6
  maximum: 35
quiet_dead_players: false
rules: null
safes:
  guard_self: true
  angel_dies: 0
  bodyguard_dies: 0
  fallen_kills: 50
  detective_reveal: 40
  doctor_shots: 0.135
  amnesiac_night: 3
spectate:
  notice: true
  include_user: true
start:
  scale: 0.3
  maximum: 4
wolfchat:
  disable_day: false
  disable_night: false
  only_kill_command: false
  only_same_command: false
  wolves_only_chat: false
  remove_non_wolves: false
  traitor_non_wolf: false

gameplay.deadchat

Whether or not deadchat is enabled. Dead players and non-players can join deadchat to speak with each other during a game. If disabled, they will be unable to speak with each other through the bot.

Default Value: true

gameplay.disable

Allows you to disable roles, game modes, and commands from being used.

Default Value:

commands: []
gamemodes: []
roles: []

gameplay.disable.commands

Commands to disable. Commands listed here cannot be used by anyone, not even admins. Use the internal command name in this list, rather than the localized name for your language. Disabling a command also disables all aliases for that command.

Default Value: (empty list)

gameplay.disable.gamemodes

Game modes to disable. Modes listed here cannot be voted or used in fgame, and will never randomly appear when there is no majority vote for a game mode. Use the internal game mode name in this list, rather than the localized name for your language.

Default Value: (empty list)

gameplay.disable.roles

Roles to disable. Roles listed here cannot be used in fgame roles, will never be chosen in game modes which randomize roles (e.g. random and maelstrom), will never be chosen as what an amnesiac will turn into, and will be replaced with the default role if it is encountered in a game mode definition. Use the internal role name in this list, rather than the localized name for your language.

Default Value: (empty list)

gameplay.gunner_wolf

Determines some interactions between gunner and attacking wolves at night.

Default Value:

kills_attacker: 25
steals_gun: true

gameplay.gunner_wolf.kills_attacker

Determines the chance out of 100 that a gunner will kill a wolf when targeted at night.

Default Value: 25

gameplay.gunner_wolf.steals_gun

Determines whether a wolf will steal a loaded gun from dead gunner.

Default Value: true

gameplay.hidden

The roles here will hide their true identity upon dying.

Default Value:

amnesiac: false
clone: false
traitor: true

gameplay.hidden.amnesiac

Amnesiac will always show up as amnesiac when dying, even if they turned.

Default Value: false

gameplay.hidden.clone

Clone will always show up as clone when dying, even if they turned.

Default Value: false

gameplay.hidden.traitor

Reveal traitor as the hidden role, typically villager, if they die before turning.

Default Value: true

gameplay.language

The language the bot uses in messages and when processing incoming commands.

Default Value: "en"

gameplay.nightchat

Whether or not nightchat is enabled in channel. If disabled, speaking privileges in the channel will be revoked from all players during the night phase.

Default Value: true

gameplay.player_limits

The lower and upper bounds of player counts for games. Note that most game modes do not support all player counts.

Default Value:

maximum: 35
minimum: 6

gameplay.player_limits.maximum

The maximum player count for players to join.

Default Value: 35

gameplay.player_limits.minimum

The minimum player count for games to start.

Default Value: 6

gameplay.quiet_dead_players

Whether or not to quiet players upon their death. Not all transports may support this.

Default Value: false

gameplay.rules

The rules for this bot, either as an embedded string or a URL, returned by the !rules command. If null, the !rules command will display that no rules have been configured.

Can be null.

Default Value: null

gameplay.safes

Defines the behaviour of safe roles, such as guardian angel, bodyguard, detective, doctor, and amnesiac.

Default Value:

amnesiac_night: 3
angel_dies: 0
bodyguard_dies: 0
detective_reveal: 40
doctor_shots: 0.135
fallen_kills: 50
guard_self: true

gameplay.safes.amnesiac_night

The amnesiac will get reminded of their true identity on this night.

Default Value: 3

gameplay.safes.angel_dies

Determines the chance out of 100 that a guardian angel will die when guarding a wolf.

Default Value: 0

gameplay.safes.bodyguard_dies

Determines the chance out of 100 that a bodyguard will die when guarding a wolf.

Default Value: 0

gameplay.safes.detective_reveal

Determines the chance out of 100 that a detective will reveal their identity to wolves when investigating.

Default Value: 40

gameplay.safes.doctor_shots

Determines how many shots the doctor gets. This floating point number will be multiplied with the number of alive players when the player gets the role, rounded up.

Default Value: 0.135

gameplay.safes.fallen_kills

Determines the chance out of 100 that, when the wolves target someone guarded by a guardian angel, the fallen angel, if present, will kill the guardian angel.

Default Value: 50

gameplay.safes.guard_self

Whether or not guardian angels can guard themselves.

Default Value: true

gameplay.spectate

Controls the behavior of the spectate command. This does not control the fspectate command, which never notifies the target chat that they are being observed. If you wish to ensure that the target chat is always notified, you should disable fspectate via gameplay.disable.commands and configure this appropriately.

Default Value:

include_user: true
notice: true

gameplay.spectate.include_user

If set, the notification sent to the target chat includes the name of the spectator. This has no effect if gameplay.spectate.notice is disabled.

Default Value: true

gameplay.spectate.notice

If set, the target chat is notified that they are being observed or no longer observed when a user begins or end spectating.

Default Value: true

gameplay.start

The settings defining how many players must do !start for the game to start.

Default Value:

maximum: 4
scale: 0.3

gameplay.start.maximum

The maximum number of !start votes that the bot can require.

Default Value: 4

gameplay.start.scale

Determines the scaling for the number of !start votes needed. This floating point number will be multiplied with the number of players, rounded up. This will not exceed the maximum below.

Default Value: 0.3

gameplay.wolfchat

Many wolf roles have access to wolfchat, which allows them to communicate with each other throughout the night and day in private through the bot. This section allows for implementing restrictions on when wolfchat may be used and who is able to use it.

Default Value:

disable_day: false
disable_night: false
only_kill_command: false
only_same_command: false
remove_non_wolves: false
traitor_non_wolf: false
wolves_only_chat: false

gameplay.wolfchat.disable_day

If set, disables all wolfchat functionality during the day. Commands will still be relayed as applicable.

Default Value: false

gameplay.wolfchat.disable_night

If set, disables all wolfchat functionality during the night. Commands will still be relayed as applicable.

Default Value: false

gameplay.wolfchat.only_kill_command

If set, only the kill command is relayed. All other commands are not. This has no effect unless wolfchat is disabled for the player using the command.

Default Value: false

gameplay.wolfchat.only_same_command

If set, commands are only relayed to roles who have access to the same command. This has no effect unless wolfchat is disabled for the player using the command.

Default Value: false

gameplay.wolfchat.remove_non_wolves

If set, non-wolves (roles that are not real wolves) are removed from wolfchat entirely. They cannot speak or see what was spoken in wolfchat, and no commands are relayed from or to them. Wolves will not know that these players are wolfteam, and the wolves can kill them.

Default Value: false

gameplay.wolfchat.traitor_non_wolf

If set, traitor is considered a non-wolf. Normally, they are treated as a real wolf for the purposes of wolfchat restrictions.

Default Value: false

gameplay.wolfchat.wolves_only_chat

If set, only real wolves (those with access to the kill command, wolf cub, and traitor) are able to participate in wolfchat. Other roles can observe what is said, but cannot speak; wolfchat is disabled for them. Their commands are still relayed as applicable.

Default Value: false

logging

The logging section defines all logging groups (collections of things to log) as well as where each group should be logged to. By default, nothing is logged; you should set up any desired logging in your botconfig.yml. Logs can be sent to a file or any defined transport (such as an IRC channel).

Default Value:

groups:
- name: main
  filters:
  - general
  - command
  - exception
  - transport
- name: admin-commands
  filters:
  - command
- name: warnings
  filters:
  - command.fwarn.add
  - command.fwarn.set
  - command.fwarn.del
- name: debug
  filters:
  - exception
logs: []

logging.groups

Logging groups. By default, the following groups are defined:

  • main: log code issues and restricted commands to stdout
  • admin-commands: log all usages of restricted commands
  • warnings: log the usages of fwarn add, fwarn set, and fwarn del
  • debug: log all exceptions that occur

Default Value:

- name: main
  filters:
  - general
  - command
  - exception
  - transport
- name: admin-commands
  filters:
  - command
- name: warnings
  filters:
  - command.fwarn.add
  - command.fwarn.set
  - command.fwarn.del
- name: debug
  filters:
  - exception

logging.logs

Which groups should be logged and where those logs should be sent to.

Default Value: (empty list)

logging.group

A collection of things to log. Logs specify which groups are written to them.

Default Value:

filters: []
name:

logging.group.filters

Only log events whose types match one of the specified filters. Leave empty to log everything.

  • command: The commands filter logs restricted commands. Specific commands and sub-commands can be used instead via command.commandname (e.g. command.fsay or command.fwarn.add).
  • exception: The exception filter logs exceptions. Specific exception types can be used via exception.type (e.g. exception.TypeError).
  • general: The general filter logs events that do not fit under any more specific filter. This is generally used by messages that are expected to be printed to stdout.
  • transport: The transport filter logs traffic sent to and received from transports. Specific transports can be used via transport.name.
  • game: The game filter logs game events, such as all executed commands and other game details. Currently unused.
  • Additional filters may be defined by Python itself and are outside the scope of this documentation.

Default Value: (empty list)

logging.group.name

The name of the group, must be unique.

Default Value: (none)

logging.log

A definition of what group to log and where to write the log.

Default Value:

format: string
group:
handler:
level: info
timestamp:
  enabled: true
  utc: true
  format: '%Y-%m-%d %H:%M:%S%z'

logging.log.format

How data sent to the log is formatted.

  • The string formatter writes a single log line (ending in newline) to the log, optionally with a timestamp in front.
  • The structured formatter sends a JSON string to the log representing an object. Exactly which fields are present in the object will vary based on the type of thing being logged. This format is useful when ingesting logs into something capable of processing the metadata and doing things with it.

Default Value: string

Allowed Values:

  • string
  • structured

logging.log.group

Group name to log.

Default Value: (none)

logging.log.handler

Defines how and where the log is written.

Default Value: (none)

logging.log.level

Only logging events of this level or more severe are sent to this log.

Default Value: info

Allowed Values:

  • critical
  • error
  • warning
  • info
  • debug

logging.log.timestamp

How the timestamp is presented in the logs. It will be prepended to string logs and available as a "timestamp" field in structured logs.

Default Value:

enabled: true
format: '%Y-%m-%d %H:%M:%S%z'
utc: true

logging.log.timestamp.enabled

If true, a timestamp is added to the log record.

Default Value: true

logging.log.timestamp.format

See the Python documentation for more information on how to configure this. It is recommended to use quotes around this field to prevent YAML from interpreting any special characters.

Default Value: "%Y-%m-%d %H:%M:%S%z"

logging.log.timestamp.utc

If true, the timestamp will be in UTC. If false, it will use the current system's time.

Default Value: true

logging.log.handler.custom

A custom handler defined via user-specified code.

Default Value:

args: {}
class:
module:

logging.log.handler.custom.args

Keyword arguments passed to the class constructor.

Default Value:

{}

logging.log.handler.custom.class

Class name of the custom handler class, should derive from src.logger.UnionFilterMixin and logging.Handler (or one of its subclasses), in that order. Subclassing one of the built-in handlers from src.logger will meet this criteria.

Default Value: (none)

logging.log.handler.custom.module

Module name that contains the custom handler class.

Default Value: (none)

logging.log.handler.file

Writes the log to a file on the disk.

Default Value:

file:
rotate: null

logging.log.handler.file.file

The path to the file to write. Can be either a relative or absolute path. If a relative path is given, it is relative to the bot root.

Default Value: (none)

logging.log.handler.file.rotate

Whether or not the files should rotate. Files can rotate when they've reached a maximum byte count or after a certain time interval has passed (but not both).

Can be null.

Default Value: null

logging.log.handler.file.rotate.bytes

Rotate the file after it reaches a certain size in bytes. See the Python documentation for more information.

Default Value:

backup_count:
max_bytes:

logging.log.handler.file.rotate.bytes.backup_count

How many old files are saved before the oldest is deleted.

Default Value: (none)

logging.log.handler.file.rotate.bytes.max_bytes

When this threshold is about to be met, rotate the file.

Default Value: (none)

logging.log.handler.file.rotate.timed

Rotate the file on timed intervals. See the Python documentation for more information.

Default Value:

at_time:
backup_count:
interval: 1
utc: false
when:

logging.log.handler.file.rotate.timed.at_time

If when is W0-W6 or midnight, this computes the initial rollover time. The value specified here should be of the format HH:MM or HH:MM:SS

Default Value: (none)

logging.log.handler.file.rotate.timed.backup_count

How many old files are saved before the oldest is deleted.

Default Value: (none)

logging.log.handler.file.rotate.timed.interval

Combined with when to determine when to rotate the file. If when is W0-W6, interval is ignored and can be omitted.

Default Value: 1

logging.log.handler.file.rotate.timed.utc

Whether or not times are interpreted to be in UTC.

Default Value: false

logging.log.handler.file.rotate.timed.when

Specifies the type of interval.

Default Value: (none)

Allowed Values:

  • S
  • M
  • H
  • D
  • W0
  • W1
  • W2
  • W3
  • W4
  • W5
  • W6
  • midnight

logging.log.handler.stream

Writes the log to a stream (stdout or stderr).

Default Value:

stream:

logging.log.handler.stream.stream

Which stream to write the log to.

Default Value: (none)

Allowed Values:

  • stdout
  • stderr

logging.log.handler.transport

Defines a transport and a location in that transport to send log messages.

Default Value:

destination: null
transport:

logging.log.handler.transport.destination

An optional location in the transport to write the log. Each transport interprets this differently.

  • For the irc transport, this should be a channel name (remember to surround it in quotes). If the irc server supports STATUSMSG, you may add a prefix to the channel object.

Can be null.

Default Value: null

logging.log.handler.transport.transport

The name of the transport to write the log to.

Default Value: (none)

ratelimits

The ratelimits section defines the various rate limits in the bot. Some rate limits are global whereas others are per-user. See the description of each for more details. All rate limits are in seconds. A rate limit of 0 means there is no rate limit.

Default Value:

admins: 300
gamestats: 0
goat: 300
playerstats: 0
rolestats: 0
start: 10
stats: 60
time: 10
votes: 60
wait: 10

ratelimits.admins

Global rate limit for using the !admins command in channel to mass-ping all admins. This limit does not apply when using the command in private, as that will not ping anyone.

Default Value: 300

ratelimits.gamestats

Global rate limit for using the !gamestats command in channel.

Default Value: 0

ratelimits.goat

Per-user rate limit for using the !goat command.

Default Value: 300

ratelimits.playerstats

Global rate limit for using the !playerstats command in channel.

Default Value: 0

ratelimits.rolestats

Global rate limit for using the !rolestats command in channel.

Default Value: 0

ratelimits.start

Per-user rate limit for using the !start command.

Default Value: 10

ratelimits.stats

Global rate limit for using the !stats command in channel.

Default Value: 60

ratelimits.time

Global rate limit for using the !time command in channel.

Default Value: 10

ratelimits.votes

Global rate limit for using the !votes command in channel.

Default Value: 60

ratelimits.wait

Per-user rate limit for using the !wait command.

Default Value: 10

reaper

The reaper section defines the grace period for certain events that indicate a player is no longer actively participating in the game. If the grace period is exceeded, the reaper will kill that player and give them warning points.

Default Value:

account:
  enabled: true
  grace: 30
  points: 1
  expiration: 30d
enabled: true
idle:
  enabled: true
  warn:
    channel: 180
    private: 240
  grace: 300
  points: 1
  expiration: 30d
leave:
  enabled: true
  points: 1
  expiration: 30d
night_idle:
  enabled: true
  points: 1
  expiration: 14d
part:
  enabled: true
  grace: 30
  points: 1
  expiration: 30d
quit:
  enabled: true
  grace: 60
  points: 1
  expiration: 30d

reaper.account

If the user changes what account they are logged into, this defines the grace time they have to switch back to their original account. Not every transport has the notion of changing what account a user is logged into.

Default Value:

enabled: true
expiration: 30d
grace: 30
points: 1

reaper.account.enabled

Whether or not account warnings are enabled.

Default Value: true

reaper.account.expiration

Expiration time for the warning applied to the user when they have the wrong account for too long.

Default Value: "30d"

reaper.account.grace

How long can a user stay logged into a different account and still remain alive?

Default Value: 30

reaper.account.points

Number of warning points to apply to the user if they have the wrong account for too long.

Default Value: 1

reaper.enabled

Whether or not the reaper is enabled. If disabled, nobody will idle out or get automatic warnings.

Default Value: true

reaper.idle

Idle time is defined as how long it has been since the user has spoken in channel. If gameplay.nightchat is disabled, the idle timer is paused during night. Warnings will be given to the user in channel and in private at certain thresholds to let them know that they need to speak in the channel.

Default Value:

enabled: true
expiration: 30d
grace: 300
points: 1
warn:
  channel: 180
  private: 240

reaper.idle.enabled

Whether or not idle warnings are enabled.

Default Value: true

reaper.idle.expiration

Expiration time for the warning applied to the user when they idle out.

Default Value: "30d"

reaper.idle.grace

How long can a user idle and still remain alive?

Default Value: 300

reaper.idle.points

Number of warning points to apply to the user if they idle out.

Default Value: 1

reaper.idle.warn

How long to wait before warning the user that they are idling.

Default Value:

channel: 180
private: 240
reaper.idle.warn.channel

Delay before warning the user in channel that they are idling.

Default Value: 180

reaper.idle.warn.private

Delay before warning the user in private that they are idling.

Default Value: 240

reaper.leave

If the user chooses to '!quit -force' during the game, this defines the applied sanctions. Note that, unlike the other entries here, this does not have a grace period, and instead will instantly applies the sanction.

Default Value:

enabled: true
expiration: 30d
points: 1

reaper.leave.enabled

Whether or not game quit warnings are enabled.

Default Value: true

reaper.leave.expiration

Expiration time for the warning applied to the user who chose to '!quit -force' the game.

Default Value: "30d"

reaper.leave.points

Number of warning points to apply to the user if they choose to '!quit -force' the game.

Default Value: 1

reaper.night_idle

Whether or not to warn users who fail to act at night. All other warning types from the reaper will override this, so that they do not stack. A user will get a maximum of one warning per game.

Default Value:

enabled: true
expiration: 14d
points: 1

reaper.night_idle.enabled

Whether or not night idle warnings are enabled.

Default Value: true

reaper.night_idle.expiration

Expiration time for the warning applied to the user when they fail to act at night.

Default Value: "14d"

reaper.night_idle.points

Number of warning points to apply to the user if they fail to act at night.

Default Value: 1

reaper.part

If a user leaves the game channel, this defines the grace time they have to rejoin it. Not every transport has the notion of leaving a game channel. Kicking the user out of a channel immediately gives them a warning and kills them.

Default Value:

enabled: true
expiration: 30d
grace: 30
points: 1

reaper.part.enabled

Whether or not part warnings are enabled.

Default Value: true

reaper.part.expiration

Expiration time for the warning applied to the user when they are gone for too long.

Default Value: "30d"

reaper.part.grace

How long can a user stay out of the channel and still remain alive?

Default Value: 30

reaper.part.points

Number of warning points to apply to the user if they are gone for too long.

Default Value: 1

reaper.quit

If a user leaves the server, this defines the grace time they have to rejoin it. Not every transport has the notion of leaving a server. Kicking the user out of a server immediately gives them a warning and kills them.

Default Value:

enabled: true
expiration: 30d
grace: 60
points: 1

reaper.quit.enabled

Whether or not quit warnings are enabled.

Default Value: true

reaper.quit.expiration

Expiration time for the warning applied to the user when they are gone for too long.

Default Value: "30d"

reaper.quit.grace

How long can a user stay out of the server and still remain alive?

Default Value: 60

reaper.quit.points

Number of warning points to apply to the user if they are gone for too long.

Default Value: 1

ssl

SSL settings that apply to all connections made by the bot.

Default Value:

ca_file: null
ciphers: ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384

ssl.ca_file

Path to a file containing all trusted Certificate Authorities (CAs). If unset, use system default.

Can be null.

Default Value: null

ssl.ciphers

All ciphers that the bot will make use of. By default, we track Mozilla's "intermediate" compatibility list.

Default Value: "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384"

telemetry

This section defines what data is sent to the lykos developers to help us improve the bot.

Default Value:

errors:
  traceback_verbosity: 0
  user_data_level: 0
  channel_data_level: 0
usage:
  game_data: false
  environment_data: false

telemetry.errors

When an error occurs, we automatically send error details to the developers. You can control what data is sent. By default, we respect the privacy of you and your users and send only a bare minimum of data that fully anonymizes your users. We do not officially support opting out of sending error telemetry.

Default Value:

channel_data_level: 0
traceback_verbosity: 0
user_data_level: 0

telemetry.errors.channel_data_level

How much data about channels is exposed in variable information and the traceback message. This can be one of the following values:

  • 0: Fully anonymize channels.
  • 1 or more: Expose the channel's name.

Default Value: 0

telemetry.errors.traceback_verbosity

Whether or not information about variable values is sent along with the error details. This can be one of the following values:

  • 0: Do not send any variable information along with the error message.
  • 1: Send variable information for the innermost stack frame along with the error message.
  • 2 or higher: Send variable information for all stack frames along with the error message.

Default Value: 0

telemetry.errors.user_data_level

How much data about the users is exposed in variable information and the traceback message. This can be one of the following values:

  • 0: Fully anonymize users.
  • 1: Expose the user's display name only.
  • 2 or more: Expose all details about the user (display name, account, channel membership, etc.).

Default Value: 0

telemetry.usage

Send data about various aspects of the bot's usage, to help lykos developers better understand how various bots are being used in the wild. This data helps focus efforts for feature development and environment support.

Default Value:

environment_data: false
game_data: false

telemetry.usage.environment_data

If true, sends information about the environment the bot is running on, including OS version, python version, and versions of all pip dependencies. This data helps the developers better evaluate what versions of things will be supported and when to drop support for older things.

Default Value: false

telemetry.usage.game_data

If true, sends information about game mode, game size, winner, and settings that impact gameplay. No data about the players themselves is sent. This data helps the developers better evaluate and tweak balance for game modes.

Default Value: false

timers

This section defines the various timers that drive gameplay. Numbers are in seconds.

Default Value:

day:
  enabled: true
  limit: 720
  warn: 600
enabled: true
join:
  enabled: true
  limit: 1800
night:
  enabled: true
  limit: 120
  warn: 60
shortday:
  enabled: true
  players: 6
  limit: 520
  warn: 400
wait:
  enabled: true
  initial: 60
  join: 25
  command:
    amount: 30
    tokenbucket:
      initial: 2
      refill: 240
      maximum: 3

timers.day

Time limits related to the day phase.

Default Value:

enabled: true
limit: 720
warn: 600

timers.day.enabled

Whether or not day timers are enabled.

Default Value: true

timers.day.limit

The time limit for day phase.

Default Value: 720

timers.day.warn

A warning is printed to channel that day is almost over at this time. Must be less than timers.day.limit.

Default Value: 600

timers.enabled

Whether or not gameplay timers are enabled. It is recommend to leave these enabled.

Default Value: true

timers.join

Time limits related to the join phase.

Default Value:

enabled: true
limit: 1800

timers.join.enabled

Whether or not join limit timers are enabled.

Default Value: true

timers.join.limit

The time limit before a game is cancelled due to being in the join phase too long.

Default Value: 1800

timers.night

Time limits related to the night phase.

Default Value:

enabled: true
limit: 120
warn: 60

timers.night.enabled

Whether or not night timers are enabled.

Default Value: true

timers.night.limit

The time limit for night phase.

Default Value: 120

timers.night.warn

A warning is printed to channel that night is almost over at this time. Must be less than timers.night.limit.

Default Value: 60

timers.shortday

Time limits for short days, which will occur once the number of living players is less than or equal to some threshold.

Default Value:

enabled: true
limit: 520
players: 6
warn: 400

timers.shortday.enabled

Whether or not short day timers are enabled. If disabled, the regular day timer section will apply regardless of player count.

Default Value: true

timers.shortday.limit

The time limit for a short day phase.

Default Value: 520

timers.shortday.players

Player threshold for number of alive players. If the number of alive players is less than or equal to this number, the timers for short days will be used instead of the normal day timers.

Default Value: 6

timers.shortday.warn

A warning is printed to channel that day is almost over at this time. Must be less than timers.shortday.limit.

Default Value: 400

timers.wait

Settings for the amount of time added after certain events before the game may be started.

Default Value:

command:
  amount: 30
  tokenbucket:
    initial: 2
    refill: 240
    maximum: 3
enabled: true
initial: 60
join: 25

timers.wait.command

This section configures how much delay the !wait command adds as well as how often it may be used.

Default Value:

amount: 30
tokenbucket:
  initial: 2
  refill: 240
  maximum: 3
timers.wait.command.amount

Amount of seconds added to the wait timer each time the !wait command is used.

Default Value: 30

timers.wait.command.tokenbucket

The !wait command uses a token bucket to determine how often it may be used. Each time the command is used, it will deduct a token from the bucket. If it cannot deduct any tokens, the command fails. The token bucket gains new tokens at a refill rate, and can store a maximum number of tokens.

Default Value:

initial: 2
maximum: 3
refill: 240
timers.wait.command.tokenbucket.initial

Number of tokens the bucket starts with.

Default Value: 2

timers.wait.command.tokenbucket.maximum

Maximum number of tokens that the bucket can contain.

Default Value: 3

timers.wait.command.tokenbucket.refill

Number of seconds it takes to add one token to the bucket.

Default Value: 240

timers.wait.enabled

Whether or not wait timers are enabled. If disabled, !wait has no effect.

Default Value: true

timers.wait.initial

The initial timer that prevents games being started too quickly after the start of join phase.

Default Value: 60

timers.wait.join

Each join that reaches a new maximum player count for this join phase will add this many seconds to the wait timer.

Default Value: 25

transports

The transports section defines all of the connections your bot will make. At least one transport must be defined for the bot to successfully run.

Default Value: (empty list)

transports.irc

A connection to an IRC network. The network must have some notion or support of accounts separate from nicks.

Default Value:

authentication:
channels:
connection:
features:
  cprivmsg: null
flood:
  initial_burst: 23
  sustained_rate: 1.73
  max_burst: 23
module: generic
name:
server_ping: 120
user:

transports.irc.authentication

Authentication settings for the network or services.

Default Value:

server:
  password: null
services:

transports.irc.authentication.server

Server authentication via the PASS command, such as if a connection password is required. If unset, we may send the services username and password via the PASS command if SASL is disabled, depending on the services and ircd modules in use.

Default Value:

password: null
transports.irc.authentication.server.password

Server connection password.

Can be null.

Default Value: null

transports.irc.authentication.services

Services authentication. We support sending regular IDENTIFY commands to NickServ (or equivalent) and support both SASL PLAIN (password-based auth) and SASL EXTERNAL (client certificate auth).

Default Value:

client_certificate: null
client_key: null
module:
password: null
use_sasl: true
username: null
transports.irc.authentication.services.client_certificate

Client certificate to connect with, in PEM format. You may either have this be a filename containing the certificate or directly embed the certificate in this configuration file (use the "|" multiline format). The private key may be optionally present in PEM format after the certificate. Leave unset if using password authentication.

Can be null.

Default Value: null

transports.irc.authentication.services.client_key

Private key to connect with, in PEM format, if it was not already specified in client_certificate. This may be either a filename containing the key or directly embedded in this configuration file (use the "|" multiline format). Leave unset if using password authentication or if the private key is already present as part of the client_certificate configuration value.

Can be null.

Default Value: null

transports.irc.authentication.services.module

What services package is in use by the network. We may vary how we send authentication details and how we recover an in-use nickname based on this selection. Configuring this wrong may have disastrous consequences. If none of the modules listed fit your connection, try using "generic" if your services package has NickServ with the IDENTIFY and GHOST commands. Otherwise, use "none" to disable services integration.

Default Value: (none)

Allowed Values:

  • anope
  • atheme
  • generic
  • none
  • undernet
transports.irc.authentication.services.password

Password to log into services with. Leave unset if using client certificate authentication.

Can be null.

Default Value: null

transports.irc.authentication.services.use_sasl

Whether or not to use SASL to authenticate. It is recommended to enable this if the network supports SASL, to ensure that the bot is fully authenticated before joining any channels.

Default Value: true

transports.irc.authentication.services.username

Username to log into services with, if the services module supports usernames different from the current nick. If unset, uses the configured nick in the user settings.

Can be null.

Default Value: null

transports.irc.channels

Channels that the bot will join upon startup.

Default Value:

alternate: []
main:

transports.irc.channels.alternate

Alternate channels. The bot will join these and respond to some commands, but games cannot be played here. If you define IRC channels as logging targets, those channels will need to be listed here as well.

Default Value: (empty list)

transports.irc.channels.main

Main game channel. Be sure to use quotes around the name so it is not treated as a comment!

Instance of transports.irc.channel.

transports.irc.connection

Describes how the bot connects to the IRC network.

Instance of connection.

transports.irc.features

Enables fine-grained control over what ircd features we use. This can be used to further customize behavior enabled or disabled by the module selection. Please use with care, as lykos may break if you enable things that the ircd does not support.

Default Value:

cprivmsg: null

transports.irc.features.cprivmsg

Whether or not CPRIVMSG is enabled. If null, use the setting determined by the module in use.

Can be null.

Default Value: null

transports.irc.flood

Settings to control how quickly the bot will send messages to IRC. The bot can send an initial burst of messages, but will slow down after a short period. This is represented using a token bucket: each message sent consumes 1 token. The bucket starts with some number of tokens (initial burst amount), and replenishes 1 token every so often (sustained rate). If no messages are sent for a while, it can accumulate up to some maximum number of tokens (max burst).

Default Value:

initial_burst: 23
max_burst: 23
sustained_rate: 1.73

transports.irc.flood.initial_burst

Initial message burst amount when bot starts (starting number of tokens).

Default Value: 23

transports.irc.flood.max_burst

Maximum number of messages we can burst at any point in time (maximum number of tokens).

Default Value: 23

transports.irc.flood.sustained_rate

Once we can't burst anymore, we can send 1 message per this many seconds (token replenish rate).

Default Value: 1.73

transports.irc.module

What IRCd the remote is running. Configuring this wrong may have disastrous consequences. If you do not see a module for your ircd, please use "generic"; some lykos features may be disabled. If you notice bugs with the generic module with your ircd, please contact the lykos developers.

Default Value: generic

Allowed Values:

  • hybrid
  • inspircd
  • generic
  • solanum
  • unrealircd

transports.irc.name

Name of this transport. Can be anything, but must be defined and unique across all transports in this file.

Default Value: (none)

transports.irc.server_ping

How often the bot should ping the IRC server to check for unclean disconnection.

Default Value: 120

transports.irc.user

Configures the bot user for this connection.

Default Value:

command_prefix: '!'
ident: null
ignore:
  hidden: true
  channel_notice: true
  private_notice: false
nick:
realname: null

transports.irc.user.command_prefix

We only respond to commands in-channel if they begin with this prefix. Commands in private with this prefix are not relayed to other players in wolfchat, deadchat, etc. Use quotes around the character to prevent YAML from interpreting it as something special.

Default Value: "!"

transports.irc.user.ident

The bot's ident. If unset, defaults to the bot's nickname.

Can be null.

Default Value: null

transports.irc.user.ignore

Certain categories of commands can be ignored by the bot.

Default Value:

channel_notice: true
hidden: true
private_notice: false
transports.irc.user.ignore.channel_notice

Ignore /notices sent to the channel.

Default Value: true

transports.irc.user.ignore.hidden

Ignore commands sent to a channel prefix (STATUSMSG), e.g. @#channel or +#channel.

Default Value: true

transports.irc.user.ignore.private_notice

Ignore /notices sent directly to the bot.

Default Value: false

transports.irc.user.nick

The bot's nickname. If already taken, we may attempt to recover this depending on what services module was selected.

Default Value: (none)

transports.irc.user.realname

The bot's realname (gecos). If unset, defaults to the bot's nickname.

Can be null.

Default Value: null

transports.irc.channel

Channels can generally be specified as simple strings, but sometimes more advanced configuration is needed under special circumstances. You can pass either a string or a full instance of this object anywhere a channel is required.

Default Value:

auto_mode_toggle: []
key: ''
name:
prefix: ''

transports.irc.channel.auto_mode_toggle

The channel modes which will be automatically toggled for the duration of the game. This is traditionally used to remove op status from players during the game.

Default Value: (empty list)

transports.irc.channel.key

Channel key, if the channel is password protected (channel mode +k).

Default Value: ""

transports.irc.channel.name

Channel name, be sure to surround with quotes so it is not interpreted as a comment!

Default Value: (none)

transports.irc.channel.prefix

All messages to this channel will be using this message prefix, if specified.

Default Value: ""

warnings

The warnings section defines the warning track in which users will automatically accumulate sactions. Sanctions can be manually applied to warnings as well.

Default Value:

default_expiration: 30d
sanctions:
- min: 6
  max: 10
  stasis: 1
  scalestasis: null
  tempban: null
  deny: null
- min: 11
  max: 15
  stasis: null
  scalestasis:
    a: 0
    b: 1
    c: -8
  tempban: null
  deny: null
- min: 16
  max: 16
  stasis: null
  scalestasis: null
  tempban: 8
  deny: null

warnings.default_expiration

The default expiration time for manually-issued warnings.

Default Value: "30d"

warnings.sanctions

The automatic sanction track. Defining your own track will overwrite the default one. Each entry in the track defines a threshold and sanctions, see the warnings.sanction type documentation for more information. These must be defined in order.

Default Value:

- min: 6
  max: 10
  stasis: 1
- min: 11
  max: 15
  scalestasis:
    a: 0
    b: 1
    c: -8
- min: 16
  max: 16
  tempban: 8

warnings.sanction

Criteria of when an automatic sanction should be applied and the definition of what sanctions to apply.

Default Value:

deny: null
max:
min:
scalestasis: null
stasis: null
tempban: null

warnings.sanction.deny

If defined, prevents the user from using this list of commands. The strings in the list should be the internal command names, not a localized version. Denying access to a command also denies access to all aliases of that command.

Can be null.

Default Value: null

warnings.sanction.max

Maximum number of active warning points the user must have before this automatic sanction stops applying.

Default Value: (none)

warnings.sanction.min

Minimum number of active warning points the user must have before this automatic sanction applies.

Default Value: (none)

warnings.sanction.scalestasis

If defined, adds this many games of stasis to the user according to the supplied formula, which is passed the total number of active warning points the user has as input.

Can be null.

Instance of warnings.sanction.scalestasis.

warnings.sanction.stasis

If defined, adds this many games of stasis to the user.

Can be null.

Default Value: null

warnings.sanction.tempban

If defined, temporarily bans the user from the channel. It can be an integer x, in which case the user is banned until enough warnings expire for them to bring them down to x active warning points or below. It can also be a string, which defines a length of time to ban the user for. The string should be a number followed by "d" for days, "h" for hours, or "m" for minutes, e.g. "3d" for 3 days.

Can be null.

Default Value: null

warnings.sanction.scalestasis

Adds stasis to the user according to the quadratic expression ax^2 + bx + c, where x is the number of active warning points the user has.

Default Value:

a: 0
b: 1
c: 0

warnings.sanction.scalestasis.a

Quadradic scaling factor

Default Value: 0

warnings.sanction.scalestasis.b

Linear scaling factor

Default Value: 1

warnings.sanction.scalestasis.c

Constant scaling factor

Default Value: 0