Dog Microphone User Manual

Table of Contents

What is Dog Microphone?

Table of Contents

Dog Microphone is a program to play board games and role-playing games over the internet. It doesn't have any rules of its own; the players supply that. Basically, you have a board with moveable tokens and a chat room. One user is the server, everyone else connects to that user and once connected, everyone sees the same board, tokens, and chatter.

To a large extent, the interface is based on trust. A player who wants to ruin the game for everyone can easily do so -- just like a real board game.


Table of Contents

Dog Microphone was programmed by Andy Sommerville, ak sommerville at g mail dot com. Please forward any bug reports or questions.

This game is in the public domain. There is NO WARRANTY from the author. You are free to use it however you like, and you are responsible for any damage caused.

Of the included graphics, all were drawn by Andy Sommerville except graphics/chessmen.png, which was modified from an image found at Hopefully they won't mind...


Table of Contents

Before running Dog Microphone, you will need the following packages:

Ubuntu users already have everything except pygame, which can be found in the default repositories:
$ sudo apt-get install python-pygame

Once the prerequisites are met, you're ready to play. From a terminal, 'cd' to the dogmic directory and enter:

Dog Microphone expects to find a data directory with directories "src" and "graphics" under it. By default, it will look in (in order):

  1. The same directory as
  2. /usr/share/dogmic
  3. $HOME/.dogmic
If you install the data somewhere else, no problem. Open in a text editor and add the new data directory, in quotes, after "POSSIBLE_DATA_DIRS=[", followed by a comma.

A few more configuration settings can be found near the top of src/

These things can all be set once running, as well.

Dog Microphone does not yet use uPnP. (in the future, perhaps?). You'll need to poke a hole in your firewall for port 8916. You can change that port, in DEFAULT_port in src/, or give it explicitly to listen or connect. If you listen on a port other than 8916, make sure your users know which to use.

Poke a hole in my firewall, you say?

It's different for every operating system and every router, but you'll need to:

For the router, usually you must log in via web browser at or whatever. Then (on a Netgear WGR614, anyway), find "Port Forwarding" and add an entry for your PC. Again, it's TCP, port 8916. The address that you use locally, like, is not your outward-facing IP address. For that, you'll have to ask the router. If it starts with 192.168, that's not the right address.

Your PC's operating system may also forbid listening on this port, if it can't distinguish Dog Microphone from a virus. To allow it explicitly will be different for every operating system, check your own documentation.

You don't need to worry about firewalls and such if someone else is hosting.

Basic Usage

Table of Contents

There are three parts of the Dog Microphone window:

Board and Palette are strictly mouse-based. Click on an object and drag it; all other users see the change instantly (even as you're moving it). To delete a sprite, drag it outside the Board area. There are arrow buttons in the palette which scroll your choices up and down. The Board area does not scroll. If the board is too big for its screen, the edges will be clipped. Make the window larger to fix this.

The Console section has Text and Command modes. In Text mode (gray entry box), anything you type is visible to other users. In Command mode (yellow entry box), you can deliver special commands to Dog Microphone. These are not visible to other users.

Hopefully, Text mode doesn't require any more explanation -- it's just IRC, basically.

Command mode will be described in more detail in its own section, but here are some critical commands:

You can also enter Dungeons&Dragons-style dice (eg "2d6") or Python expressions, more on those later.

Press TAB to switch between Text and Command mode. This does not clear the contents of the entry field.

Some other keys:

Image Format

Table of Contents

Dog Microphone will only open images from its "graphics" directory. For boards, it will open any format supported by pygame -- this can vary from installation to installation, but should include PNG, GIF, BMP, and JPEG. (Formats other than those four, you'll need to add them to ALL_IMAGE_EXTS in src/

There are two required images -- font.png and deco.png. These may only be in PNG format. deco.png must be 64x64 pixels, and contains the Palette's scroll button images. font.png is 16x6 tiles for the characters 0x20..0x7f (the printable ASCII characters). font.png must be 1-bit indexed, with color 0 as the background. It can be any size (as long as it produces 16x6 identical tiles).

Boards can be any size, but be reasonable -- remember that the Board area has no scroll bars.

Tiles images must be PNG format, as we use a non-standard extension chunk for the grid geometry. These should be 32-bit RGBA (but don't need to be), and should be divided into a grid with up to 256 cells. When you load a Tiles image, you may indicate the cell size in pixels. Dog Microphone will store this information in the file, so you only need to specify it once per file. The extension chunk is marked COPY-SAFE, per the PNG standard, but not all editors will preserve. (The GIMP does not).

For the curious, our extension chunk is type "tiLe", and is the 2-byte big-endian column width followed by 2-byte big-endian row height.

Images are transferred between clients in their file format. If you are having bandwidth problems, you'll get better results from heavier compression than from cropping (usually).

Command Mode

Table of Contents

Dog Microphone decides how to interpret a command based on its first word. If it doesn't match a keyword, it tries first "roll", then "eval". (typically, you can enter "roll" or "eval" arguments without the keyword).

Miscellaneous commands
helpPrint a brief summary of all commands.
exitQuit Dog Microphone.
name [NEW_NAME]Query or set user name, when not connected.
whoShow names of all remote users.
log none|FILE_NAMEEcho Console output to file (or disable echo).
verb TEXT Add a sentence to the chat: USER_NAME TEXT
For example, if your user name is "Joe", say "verb is awesome!" and all users will see:
> Joe is awesome!
Network control
listen [[ADDRESS] PORT]Open the server, wait for incoming connections.
unlistenStop accepting connections (keep existing ones).
connect [ADDRESS [PORT]]Connect to remote server.
disconnect [NAMES...]Break connections (server may close specific clients).
Image loading
board NAME Replace the current board with a local file. You need specify only the stem of the file name, eg "chessboard" opens "graphics/chessboard.png".
tiles NAME [COLUMN_WIDTH [ROW_HEIGHT]] Add a tile set to the Palette. If COLUMN_WIDTH is given but ROW_HEIGHT is not, cells are presumed to be square. Cell dimensions must be given the first time loading a Tiles image. You'll be reminded if you forget.
rmtiles NAMEUnload the named Tiles image.
clearspritesRemove all Sprites (Tiles dragged out of Palette).
textsprite [COLOR] TEXT Create a sprite of text. Initially centered upon the board. Color is in HTML format ( "#ff0000"=red "#00ff00"=green "#0000ff"=blue ), and may appear at beginning or end of arguments. Default color is white.
deck NAME Load a new deck of cards (from "graphics" directory). Do not remove existing decks. A deck is a text file where each not-empty line is a card. Each line must be unique.
rmdeck NAMERemove a deck and quietly remove its cards from everyone's hand.
shuffle [NAMES...]Shuffle all decks (or the named decks).
decksShow the name and size of each loaded deck.
cardsShow your hand (not visible to other users).
draw [DECK] [COUNT] Draw the given count of cards from the given deck. Deck need not be named if only one is loaded. Count defaults to one.
discard [CARDS...] Return cards from your hand to the deck. With no arguments, return the whole hand. Arguments are 1-based indices, as listed by cards.
givecard CARD USER Give a card from your hand to another user. All users will see that the exchange took place, but only you and the recipient can read the card. CARD is an index as in discard.
showcardsShow your hand to all players.
Extended evaluation
roll EXPRESSIONRoll dice.
eval EXPRESSIONEvaluate Python statement.

Dice expressions

Use the Dungeons&Dragons syntax: COUNT 'd' SIZE. COUNT must be at least one, and SIZE must be at least two. For counts up to eight, each die is listed individually. Above eight, a summary (sum, low, high, mean) is printed. Every user can see the result of every die roll.

It's a pleasant coincidence that expressions conforming to dice syntax can not be legal Python. You should never need to explicitly declare a command as a die roll: "2d6" and "roll 2d6" do the same thing, and are equally unambiguous.

Python statements

It's way beyond the scope of this manual to teach you Python, but I won't assume that you already know the language. The two most common things you'll do with Python expressions are assignment and arithmetic.

To assign to a new variable, use "NAME = VALUE". To modify a variable, use '=' with an operator in front of it, eg:
hp -= 5
means "reduce hp by 5", 'hp' having previously been created.

To lookup the value of a variable, or to evaluate arithmetic, simply enter the expression, eg:
(which yields 5 and not 45, proving that parentheses are handled correctly). Or:
(which yields 45, proving that the order of operations is acknowledged).

Python uses a set of operators similar to C and many other programming languages. The most important are:

The 'math' and 'random' modules are pre-loaded, for example you can use "math.sqrt(n)" or "math.pi".

There's a built-in class called Object which can be used as a container for variables. Consider this example:

We can then query "joe.hp" and see that it is 100. Or, we could query "joe" and get a listing of every field.

You can execute conditions, loops, and definitions if they fit on a single line. You can use "import" freely. (for those not familiar with Python, don't worry about it).

Included Data Files

Table of Contents