Libretro Client Introduction, Arcan

A key quality aspect of any API such as libretro is that there are multiple, independent, actors on both sides of the imaginary fence that the API represents; Multiple applications using an API (what we typically mean with “client” or “frontend”), and multiple implementations (what we mean when we say “core”). In a perfect world, you can mix and match clients and cores to your hearts desire and adapt things to fit your own specific needs.

In the emulation world, this is one aspect that sets the libretro project apart from many others in that it is not, as some critics may cry “a bunch of emulators bundled together like some weird game of katamari damacy” but rather an attempt to retrofit emulators (and nostalgic game engines) with an API so that they may be used on more hardware and software platforms and for additional purposes (validation, automated test suites, …).

Those of you reading this already know about RetroArch, the reference client with the primary goal of being clean, fast and extremely portable. There are others, and this post is to tell you of one of those, namely Arcan (http://arcan-fe.com).

One of the primary goals for Arcan is balancing versatility (being used for fun, weird and odd things), security, speed and portability. In the software world, it sits there quietly in a corner somewhere (and rather alone) between being a windowing system (like X or Weston), a game and graphics programming framework (like Love2D, Cocos2D, VisualTK, …), a hacking and reverse engineering framework and, indeed, a libretro client. The rest of the post will be dedicated to the libretro- related parts.

The first thing to cover is that Arcan is entirely script driven. You select some scripts to run (‘theme’) and that defines what Arcan will actually do. There are two major such themes, Gridle (that tries to mix and match styles from arcade frontends like Hyperspin, Wah!Cade and AdvanceMenu) and AWB that behaves more like a desktop environment but with some unexpected features that can be used to rather extreme ends. The screenshot below, for instance, shows one instance of Arcan with AWB running two instances of Arcan, one of them also running a libretro core. The display is simultaneously mapped to a 3D model.

The sets of pictures here (Gridle Examples) and here (AWB Examples) try to show a little more in-depth of what these two themes are up to. For those that prefer videos, this slightly dated youtube playlist shows a bit more on how things work. To work properly, the initial configuration in Arcan is slightly more difficult in the sense that you don’t just pick a game and a core and off you go, there’s an additional step involved in order to prevent nasty written scripts to do bad things to your computer.

Arcan expects all file operations to happen inside two folders, “resources” and “themes”. Resources are for save-states, additional artwork, data files (roms) and cores. An additional tool (“arcan_romman.rb” on Linux/BSD and arcan launcher on Windows) performs the job of scanning through the resource folder and to download extra artwork, metadata (like title, genre) and so on. This is done by scanning two subfolders, resources\targets and resources\games. You stuff your cores (like snes9x.dll) in the targets folder, create a corresponding subfolder like (resources\games\snes9x) where you put your roms and tell the tool to start building a database. Enough with the boring stuff, look on the Arcan wiki for more details.

To round this brief introduction off, lets demo a short script that launches two random games side by side, forwarding some input to both of them. To use / run, create a folder in your themes subdirectory called retrodemo and a file named retrodemo.lua inside the new folder. Type in the codeblocks below (or use the pastebin link).


function retrodemo()
-- load a translation table to get decent names for keypresses
symtable = system_load("scripts/symtable.lua")();

— query the database and return a table of all entries for a target called ‘snes’
games = list_games({target = “snes”});

— give up if nothing was found
if (#games == 0) then
shutdown(“empty database, can’t proceed.”);
return;
end

— launch two randomly selected games and save the handles for later
— game_callback is a function reference that will be called every time
— something happens in the core that we want to be alerted about
game_1 = launch_target(
games[math.random(#games)].gameid,
LAUNCH_INTERNAL,
game_callback
);

game_2 = launch_target(
games[math.random(#games)].gameid,
LAUNCH_INTERNAL,
game_callback
);

— place the two games side by side
move_image(game_2, VRESW * 0.5, 0);
show_image({game_1, game_2});
end

This function will be called when the engine is ready to run, all subsystems have been created and are up and running. We immediately launch two cores, but this still misses a callback and an function to handle input.


function game_callback(source, status)
if (status.kind == "resized") then
resize_image(source, VRESW * 0.5, VRESH);
end
end


This function will be called a lot, when the core has a frame ready, information about save state and other capabilities, if the emulation dies for any reason and so on. The first event is almost always “resize”, so we use that to force it to take up half the display.

Lastly, some input handling:

-- create a global input table that translates wasd,1 and ctrl/alt to special inputs
-- the libretro frameserver can handle.
keymap = {};
keymap["w"] = "PLAYER1_UP";
keymap["s"] = "PLAYER1_DOWN";
keymap["d"] = "PLAYER1_LEFT";
keymap["a"] = "PLAYER1_LEFT";
keymap["d"] = "PLAYER1_RIGHT";
keymap["1"] = "PLAYER1_START";
keymap["LCTRL"] = "PLAYER1_BUTTON1";
keymap["LALT"] = "PLAYER1_BUTTON2";

— this function will be called on any input received (including mouse, gamepads, etc.)
— for now, just check if its a translated device (aka keyboard)
function retrodemo_input(input)
if (not input.translated) then
return;
end

— translate the input using the table above
local key = keymap[ symtable[input.keysym] ];

— if it was a valid key, forward it to the two running cores.
if (key ~= nil) then
input.label = key;
target_input(game_1, input);
target_input(game_2, input);
end
end

In closing, there is a ton of stuff to explore and play around with in Arcan (humorously called ‘the emacs of frontends’ by some, though it should of course be vim..) — both for power users and for those of you with an interest for the lighter sides of programming.