Forum | Features | Download | Addons | Help | #emech | Links | About | Contact

Versions | News Archive | Installing | Linking | Configuration | Commands | FAQ

Basic concepts

Details of a command

EnergyMech commands are often described in a terse `usage' line. The format of this line is quite simple, describing the name of the command, its required arguments and its optional arguments.

In the EnergyMech documentation, command names are written in all upper case, its required arguments are enclosed in less-than ( < ) and greater-than ( > ) signs and its optional arguments enclosed in brackets ( [ ] ). The pipe character ( | ) is used where there are more than one valid argument or list of arguments. Consecutive dots ( ... ) are used where any number of arguments may be used. Literal arguments are typically written in all upper case aswell.

Lets examine an example command description;

Usage: SPY <channel|STATUS|MESSAGE|RAWIRC> [channel|">" filename]

Translated into to plain english this would be read something like;
Usage for the command SPY which has a required arument of a channel name or the string STATUS or the string MESSAGE or the string RAWIRC followed by an optional argument of a channel name or the literal character > followed by a filename.

Defining a feature

When this document talks about defining a feature it usually means that you have to manually edit a `#define' in the config.h file before you compile your EnergyMech. Defines are used in the EnergyMech source code to include or exclude the features that you select. Since defining affects what code is actually compiled into the EnergyMech binary, you have to recompile your EnergyMech if you notice that you need a feature that you havent already included or forgot to include.

The configure script will suggest what features to include or exclude when you run it and will then create the config.h file from a template (config.h.in). There are defines in the config.h file that aren't mentioned in the configure script because they are obscure, highly technical (such as ASSUME_SOCKOPTS) or extremely dangerous (such as PLEASE_HACK_MY_SHELL).

Note that if you run configure again, any manual changes you have made to the config.h file will be overwritten by the values in the template (config.h.in) and your selections made in the configure script.

Conclusions:

Editing the config.h file allows more control over EnergyMech features.
Manual changes are lost when the configure script is re-run.

Terminology

Terms used

config.h: This file is part of the EnergyMech source code. It defines many fundamental settings that is used throughout the sourcecode. Most significant is the defining of which features to include code for.
configure: This is the shell-script that is executed to prepare for the compilation of your EnergyMech. It auto-detects and checks for the different things that is required to build a working EnergyMech binary. It also suggests and asks what features should be included when building the binary.
configuration file: When the EnergyMech is started it reads all settings from the configuration file (by default this file is named mech.conf). The configuration file contains commands that are sent to the command parser just as all online commands are. These commands are executed in the exact same way as online commands would be, with a few exceptions (most noticeably, the NICK command).
feature: Features are typically major components that can be defined or undefined in order to include or exclude them from the final EnergyMech binary. Some features are part of the EnergyMech core and can not be excluded.
head: An EnergyMech process with more than one bot configured is usually said to be multi-headed. A head would be a single bot in a process with many bots configured. The term bot could also be used in the same way but is not as unambiguous.
process: This is the term usually used to talk about the whole EnergyMech process, including all bots, configuration items, etc.

Signals

Signals are handled by the first bot to be added to a process. The SIGHUP and SIGUSR1 procedures will only affect the first bot that is added. No other bots will be affected.

SIGHUP: Read and execute all commands in `mech.msg' file.
SIGINT, SIGTERM: Exit gracefully. Saves session file if sessions feature is supported. Saves trivia scores if trivia feature is supported. Sends death message to uptimes server if uptimes is supported.
SIGUSR1: Jump (a) bot to the next server in the serverlist.
SIGUSR2: Dump all debug information to a file. This signal is only handled if you have compiled your EnergyMech with debug support.

Userlist

Associated commands:

ACCESS [channel] [nick|userhost]
ADD <handle> <channel|*> <nick|mask> <level> [password]
PASSWD [oldpassword] <newpassword>
SETPASS <handle> <password>
VERIFY <password>

Command Aliases

Associated commands:

ALIAS [alias [replacement format]]
UNALIAS <alias>

TCL Scripts

Associated commands:

TCL <command>
TCLSCRIPT <filename>

Note that the TCL command is only available if you manually define PLEASE_HACK_MY_SHELL in the config.h file before compiling.

The DCC filesend

To use this feature you need to put the files you wish to transfer in a "public" subdirectory. If you for example run the EnergyMech from the directory "/home/luser/emech", you need to place the files you wish to make available in a directory called "/home/luser/emech/public".

On the IRC side, a user can simply type ".send <filename>" for the EnergyMech to send the file to them via DCC. Depending on how you set the command level for the 'send' command, it can be made available to the public. Change the command level to 0 (zero) to make it available to any user. The default command level for the 'send' command is 10 (ten) which would require users to be in the userlist in order to use the command.

The IRC Proxy

To enable the IRC Proxy, you need to add one line to the mech.conf file;

set bncport <portnum>

portnum is the port that you want it to listen for connections on. Once its listening (you can check this in debug mode), you connect with your IRC client to the port and follow the on-screen prompts...

You will be prompted for a handle and a password which needs to be in the userlist. The user record also needs the special +BNC flag to be allowed access to the IRC proxy.

To set this flag for a user record, use the command;

user <handle> +bnc

The final step is to enter which server to connect to. You can also specify a port and a virtual host if there is any available.

The line could look something like;

irc.chatserver.net 6667 my.vanity.domain.com

Both the port and virtual host is optional. If you dont specify a port, it will connect on port 6667. If no virtual host is specified, it will connect from the default interface of the shell box, which is usually what you go with.

You should probably ask your shell administrator for permission before running an IRC proxy. Shell admins typically charge for 2 background processes, one process for a bot and one process for an IRC proxy. The E3 combines these two elements into the same process and some admins could probably be a bit ticked off (most admins are cheap, they feel like you're cheating them out of their money when you squeeze more features into a single background process...).