@ Necklace of the Eye

How to create configurations

Note: NotEye is still under development. You can play with provided configurations, but if you try to communicate using the NotEye protocol or to create a sophisticated configuration or something else, you would probably run into some problems, because many things are not documented yet, and some things which should work do not (some special cases which I have not found use for yet, this happens mostly with 3D and ISO views). I prefer to finish and then write the docs. If you want to work with NotEye already, but don't understand something, please send me an e-mail to zeno@attnam.com.

Note: you can run NotEye with a parameter (e.g. noteye noteye.log), this way any problems will be sent to a diagnostic log file.

You should probably start from one of the configurations provided as examples (frozen.noe, crawl.noe, doomrl.noe, adom.noe — hydra.noe contains lots of hacks to make NotEye display hex and is more difficult). Copy it to gamename.noe and add it to the menu in the noteye.noe file.

The amount of work depends on how original the game's display is, and how complete do you want your tileset to be. In some cases it should be enough to simply copy one of the provided configuration files, and modify some numbers. Usually you will need to modify the mapregion variable. It says which part of the screen contains the map in the given roguelike. If there is something original, or you want more complicated features, you will probably need to learn some Lua and understand how NotEye works.

'caller' is a script that either runs the game or tells the users to care for themselves. The first parameter of caller3 is the full game of the name, and the second one is used as both the name of the executable and the name of the directory where the game is expected to be found.

Lua is designed so that you can replace functions by your own implementations (which can call the original ones), and NotEye uses this. If you want to provide tiles for more things, it is probably the easiest to modify the xtileaux function (copy the implementation from the DoomRL or ADOM config and modify it). If the game incorrectly guesses the position of the player character, you can try changing the ispc function (like hydra.noe which makes sure that the @ sign is white, so that we don't take an e-mail address for a map), or the copymap function if the first method does not work. If you don't like how some things are colored on the minimap, change the xminimap function. And so on.

OK, here is a short description of concepts available in NotEye:

Object

Objects include images, fonts, tiles, screens, and game processes. You create objects by calling functions implemented by NotEye, and use them by calling other functions. These functions return numbers which act as identifiers for these objects. You can use delete(x) to delete objects, and objcount() to know how many objects have been allocated so far.

Image

Images are just that, images, that is, rectangular blocks of pixels. The following Lua functions work on images:

newimage(x, y, color) — create a new image of given size, filled by the given color (returns the index of the image)
loadimage(filename) — create a new image by loading it from the file (returns the index)
saveimage(I, filename) — save an image to a file
setpixel(I, x, y, color) — sets a pixel in an image; color is given in RGB, e.g. 0xFF8000 = orange. Columns are indexed from 0 to X-1, and rows are indexed from 0 (top) to Y-1 (bottom).
getpixel(I, x, y) — gets a pixel from an image
imgcopy(I1, x1, y1, I2, x2, y2, width, height) — copy a fragment of I1 to I2

Graphics to display

Gfx is an Image, so saveimage, setpixel, getpixel, and imgcopy functions work on it — you need to give Gfx (which equals 1) as the image. Also the following are required:

setvideomode(X, Y, F) - set the given resolution, F says whether we want to set full screen mode. Returns true if successful, false if not successful.
updaterect(X, Y, W, H) - copy a rectangle from Gfx to be in fact displayed on the screen.

Screen

A screen is a rectangular block of Tiles. Screens can be drawn on an Image, and also can be connected to a Process, so that the Screen contains the console output from a roguelike.

newscreen(X, Y) - create a new screen of given size (returns the index). Columns are indexed from 0 to X-1, and rows are indexed from 0 (top) to Y-1 (bottom).
scrwrite(S, X, Y, text, Font, color) - write on the screen S at position (X,Y), using given font and color.
scrget(S, X, Y) - get a Tile at the given position.
scrset(S, X, Y, Tile) - set a Tile at the given position.
scrcopy(S1, X1, Y1, S2, X2, Y2, SX, SY, F) - copy a SX x SY fragment of the screen S1 at position (X1,Y1) to screen S2 at position (X2,Y2). This function can not only copy the screen, but also modify it in arbitrary ways, for example replace a character with its minimap or graphical tile. Function F(T,x,y) is called for each tile, with parameters T - the tile in the original screen, x,y - the coordinates (relative to the S1). (You can use eq for F if you want to simply copy.)
scrfill(S, X, Y, SX, SY, T) - fill a SX x SY rectangle at position (X,Y) in screen S with tile T.
scrsave(S, filename, type) - save a HTML or phpBB screenshot (depending on type) of S to filename.
drawscreen(I, S, X, Y, TX, TY) - draw the screen S on image I, at offset (X,Y), with tiles of size (TX, TY).

Tiles

Screens are made of Tiles. This is a general concept that encompasses both console characters that roguelikes output and the tiles shown on screen, and even is allowed to include 3D information about how a tile will look in the FPP view. You can create new tiles with the following:

addtile(I, X, Y, SX, SY, trans) - create a tile by cutting the rectangle from the image I at (X,Y) size (SX,SY). The value 'trans' contains the color that is interpreted as transparent (use -1 if the tile is not transparent). Note: tiles are sometimes cached, so if you modify the image, the tile might be changed or not.
tilefill(color) - a tile filled with color C. (In FPP mode this is currently supported only for floors and ceilings.)
tileshade(color) - a semi-transparent tile filled with color C. (Also partially supported in FPP)
tilemerge(T1, T2) - create a new tile by superimposing T2 on T1.
tilerecolor(T, C) - recolor a tile using color C. Recoloring does not change the shades of gray, only the pixels which have some saturation. Technically, it calculates the minimum and maximum component, and replaces each component by a value that is also between this minimum and maximum, but based on C.
tilespatial(T, S) - specify how the tile T will look in 3D (by returning a new index which has this information inside). You can use spFloor, spCeil, spWall, (draw as a part of the floor/ceiling/wall, respectively), spMonst (draw large objects in front of the cell), spItem (draw small objects). You also need to add spFlat if you want the tile to be shown on 2D screens too.
tiletransform(T, DX, DY, SX, SY) - moves the tile by (DX,DY) and resizes it (SX,SY) times. For example, tiletransform(T, -0.5, 0, 2, 1) makes the tile two times wider (2), and the left edge moved by 0.5 of the original width to the left (in effect, the center remains the same). This is not supported in FPP.

These functions return the tile index that you can use on screens.

Fonts

Fonts are created with F = newfont(I, x, y, trans). I is an image which contains the characters. There are x characters in each row, and y columns (there should be x*y == 256). The value 'trans' contains the color treated as transparent. You can get the tile for the given character with fget(F, ch), e.g. fget(F, "@").

Process

Processes are games, command shells, and other things that NotEye can run and process its screens.

newprocess(Scr, Font, cmdline) - create a new process. The process will use the screen Scr as its display, and use the font Font. Commandline is given as cmdline.
sendkey(P, Event) - send a keydown/keyup event to the process P (see events later).
proccur(P) - get the cursor position from the process P, as a {x=..., y=...} table.
processactive(P) - tell if the process is still active (although you should know that anyway).
vgaget(i) - processes use a 16 color palette. This function gives the 24-bit color associated with the given index; also the next four bits contain the original palette index (this has no use yet, but in future is planned to be used to translate the color back to a 16 color palette). (Currently this is not associated to a process, although it maybe should.)
vgaset(i, color) - change the palette.

The screen associated to a process is filled with tiles of form:
tilemerge(tilefill(vgaget(BACKGROUND)), tilerecolor(fget(Font, CHAR), vgaget(FOREGROUND)))
which can be correctly displayed using drawscreen. You can also process this form using functions gch (get character), gco (get foreground color (as a full color, not palette index), gba (get background color), gp2 (get just the character, without the background).

(to be continued)

You can contact me at zeno@attnam.com, or at RogueTemple or New Attnam forums (Z), or at my blog.

Return to NotEye
Thanks to Slashie for hosting this at RogueTemple!