Mambo

Mambo is an extensible teamspeak 3 chat bot. If you're using the bot, or have written some scripts for it, please let me know, I'd love to hear what your doing if you don't mind sharing it.

Getting Started

Requirements

• Erlang (R16B or later) - there are pre built packages in the Erlang Solutions Downloads page
• Elixir - see here for installation instructions
• Server query login credentials
• The script gif.ex also requires ImageMagick to be installed.

Some plugins require access to certain APIs:

• Twitter for twitter.ex
• WolframAlpha for wolframalpha.ex
• YouTube for youtube.ex
• LastFM for lastfm.ex

Use the above links to register an account and get your API credentials. If you don't plan to use the above plugins you can skip this.

Settings

Once you have sorted the dependencies you can start configuring the bot. Everything related to configuration is done in the settings.json file.

settings.json

• name: Nickname that will appear in the chat
• user: Server query username
• pass: Server query password
• host: Server ip address
• port: Server query port
• bot_id: Bot unique id, it's important that this value is right or the bot will not work properly
• admins: List of admins unique id, required if you plan to use the admin.ex script
• channels: List of the channels the bot will join, this can be either a list of channel ids or the string "all" to join all the channels
• scripts: List of scripts that the bot will use, put only the scripts you want to use

Use the file settings.sample.json as a guide, edit the values that you don't like, remove the scripts you don't want to use from the list and when you're happy rename it to settings.json.

Compile and run

When you have a working installation of elixir and the bot is properly configured, download the source code and extract it to a directory of your choosing. Open a terminal window and do the following:

$ cd path/to/mambo
$ mix do deps.get, compile

If everything went ok you now have compiled the bot, next step is to actually get it running, you have 2 choices:

To run the bot without a shell and in the background do:

$ elixir --detached --no-halt -S mix

To run the bot with an elixir shell do:

$ iex -S mix

I recommend running the bot with an elixir shell, this way you can have some feedback and easily manage the bot without turning it off (see Managing the bot for more info). In Linux (and Mac OS X too I guess) you can use tmux or screen to keep the shell running. I don't know about Windows, google is your friend here.

Scripts

Mambo by itself doesn't do much, but don't worry, it's extensible via scripting, you can add new functionalities by writting your own scripts and/or using the provided scripts.

Note: Type .help in the chat to know more about the running scripts.

Here's the full list of provided scripts:

Script	Commands
admin.ex	.mute,.unmute,.gm <message>,.rename <name>
benis.ex	.benis <expression>
brainfuck.ex	.bf <brainfuck_expression>
cannedreplies.ex	cool,gface,goface,edgyface,dface,ggface,chownface
eightball.ex	.8ball <question>
gif.ex	.gif <gif_link>
google.ex	.g <phrase>,.google <phrase>,.img <phrase>,.image <phrase>,.images <phrase>
help.ex	.help
lastfm.ex	.np,.np <last.fm user>,.np set <last.fm user>
private.ex	.private
quotes.ex	.quote,.quote <id>,.quote add <quote>,.quote find <search query>,.quote rm <id
rainbow.ex	.r <expression>,.rainbow <expression>
random.ex	.roll,.rock,.paper,.scissors
sux.ex	.sux <expression>
title.ex	none
translate.ex	.tl <phrase>,.translate <phrase>,.translate <input language> <target language> <phrase>
twitter.ex	none
urban.ex	.ud <term>,.urban <term>
utils.ex	.ping,.date,.time,.uptime,.version
whatthecommit.ex	.wtc
wolframalpha.ex	.wa <expression>,.calc <expression>,.convert <expression> to <units>
youtube.ex	.yt <phrase>,.youtube <phrase>

Scripting

Scripts can either be written in elixir or erlang, they all are gen_event handlers, see [1] and [2] for more info. Look at already written scripts to know how to write your own.

Once you have written your script place it in the lib/scripts folder and add it to the scripts list in the settings.json file.

Events

Scripts will receive notifications of the following events:

Event	Notification message
chat message	{:msg, {msg, name, {cid, clid, uid}}}
private chat message	{:privmsg, {msg, name, {clid, uid}}}
moved into channel	{:move_in, {tcid, reasonid, clid}}
moved out of channel	{:move_out, {tcid, reasonid, clid}}
left the channel	:left
entered the channel	{:enter, name}

Types

• msg = String.t() - message written in the chat
• cid = integer() - channel id (channel were the event happened)
• tcid = integer() - target channel id (the client moved to channel with id tcid)
• clid = integer() - client id (client that triggered the event)
• reasonid = integer()
• name = String.t() - username of the client that triggered the event

Exports

The modules Mambo.Bot and Mambo.Brain implement various functions meant to be used by the scripts:

Mambo.Bot

• id/0
• admins/0
• scripts/0
• send_msg/2
• send_privmsg/2
• send_gm/1
• kick/2
• ban/3
• move/2
• move/3
• mute/1
• unmute/1
• rename/1
• add_watcher/1
• remove_watcher/1

Mambo.Brain - bot's memory

• add_quote/2
• find_quotes/1
• remove_quote/1
• get_quote/1
• get_random_quote/0
• quotes_max/0
• add_lastfm_user/2
• get_lastfm_user/1
• remove_lastfm_user/1
• put/2
• get/1
• remove/1

If you need an http client in your script use hackney. If you need to decode or encode json use jsx. They will both be installed when you do mix deps.get during the installation procedure.

Managing the bot

Note: This requires to start the bot with iex -S mix.

All the functions mentioned in exports are available for you to use in an elixir shell.

To manage scripts, load, unload, notify or get a list of the running scripts, use the API from the module Mambo.EventManager.

This should be enough to manage the bot without ever shutting it down, even adding new plugins.

Getting help

You can get help by making an issue on GitHub, or going to the official thread in the teamspeak forums. If you are already knowledgable about Mambo, please consider contributing for the sake of others.

License

All files under this repository fall under the MIT License. Check LICENSE for more details.