R4 script

R4 script is the small programming language built into R4, an OpenGL music visualizer written by Gordon Williams under the name RabidHamster. R4 draws animated 3D graphics that “twist and turn with the music,” and almost everything it puts on screen is defined by a scene: a .r4 text file written in a C-like language that the program compiles and runs many times a second. The language never had a life outside R4. It is the way you told a 2004-era visualizer what to draw, and it is remembered today mostly by the people who wrote scenes for it, by one entry in the “99 Bottles of Beer” collection, and, less happily, by a 2012 security advisory against the program that hosted it.

History and Origins

The R-series

R4 was the fifth in a line of visualizers Williams wrote for the Winamp media player. Pur3, the company he later formed, lists the lineage as R1, R2, R2v2, R2/Extreme and then R4, and dates the first R2 visuals to around 2001, when Williams was a student. The R2/Extreme page describes that fourth-generation plugin as already ambitious: 25 OpenGL scenes that could be combined, “scene fades” between them, an in-plugin user interface, a control console with bindable keys, and a telnet server in the professional version. R2/Extreme, by the site’s account, found its way into nightclubs and events, including Glastonbury and a Ministry of Sound New Year at the Millennium Dome (Morphyre’s later history page attributes that event to R4 instead, so the exact generation is uncertain).

R4 (2004)

R4 took that idea and made two changes that mattered for the language. First, it became a standalone program as well as a Winamp plugin, reading audio straight from the sound card. Second, and more important, it exposed a full scripting engine so that scenes were no longer hard-coded: a scene became a program. R4’s own change-log starts at “0.02 BETA : Public Release” and climbs through the 0.x betas - adding faders, overlays, an HTTP server and the scripting console - to version 1.00 and beyond. The log is undated, but the betas appear to belong to 2003. WinampHeritage dates the R4 1v20 plugin build to February 2004, and the bundled Java scene-builder “R4Construct” carries April 2004 file dates. By Pur3’s later reckoning R4 was downloaded by more than 1.4 million people and used in music venues around the world; the professional, brandable version sold for GBP 95.

After R4

Development wound down at the end of the decade. Williams, trading as Pur3 Ltd, spent about three years building a successor, the Morphyre visualizer, and released it in September 2009; R4’s pages began pointing visitors to Morphyre, and the final R4 build, 1.25, dates from around January 2010. Williams went on to create the Espruino JavaScript microcontroller. R4 itself resurfaced in 2012 when Luigi Auriemma published buffer-overflow and directory-traversal bugs in its optional web server, catalogued as CVE-2012-10058.

Design Philosophy

The language exists to serve one program, and its design shows it. The tutorial states the goal plainly: R4 script “is basically a stripped-down version of C,” so “learning R4 programming is much easier if you are familiar with C/C++ or Java.” It keeps C’s shape - braces, semicolons, if/else, for, while, do/while, functions - and throws out most of the rest. There are two number types, int and float, and nothing else scalar: no boolean type (true is 1, false is 0), no character type, and strings faked as int arrays. There are no ++ or -- operators and no /* */ comments, only //. Identifiers are case-insensitive. A function returns a value by assigning to a magic variable called result.

What the language adds instead is a vocabulary for real-time graphics. A scene is built from modules - SOLID, TEXTURE, GL, MAP, TUNNEL, MEDUSA, BUFLOAD/BUFSAVE and many more - that are declared in a header and then driven from code, and it hands the author the audio: soundA, soundB and soundC for bass, mid and treble energy, and 512-element waveLeft/waveRight and specLeft/specRight arrays for the waveform and its Fourier transform. This is a language whose “standard library” is a set of drawable objects and a stream of sound.

The Language

A scene

Every scene has the same skeleton: a header that names its modules, then three callbacks. init() runs once when the scene loads, reset() runs each time the scene becomes active, and render() runs before every frame.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

SCENE (
    "name"   = "Example Scene";
    "author" = "Jussi Harkonen";
    SOLID   background();
    TEXTURE texFish();
    MEDUSA  fish(background, texFish);
)

int numFishes;
const int MAX_NUM_FISHES = 10;

void init() {
    // one-time setup
}

void reset() {
    numFishes = 0;   // re-initialise per activation
}

void render() {
    // runs every frame
}

Module member variables are reached with a dot, and colours are packed into a 32-bit integer:

1

red.col = rgb(1, 0, 0);   // set a SOLID module to red

C, minus a lot

The everyday syntax is C with sharp edges. Numeric literals decide their own type, so division is a trap the tutorial warns about:

1
2

var2 = var1 / 5;     // integer division
var2 = var1 / 5.0;   // floating-point division

const values must be plain non-negative literals (no expressions, and floats need a visible decimal), strings live in int arrays and are handled with strcpy/strcat, and a return value comes back through result:

1
2
3

float randNum(float minVal, float maxVal) {
    result = minVal + ((maxVal - minVal) * rand());
}

Shaders

Modules are textured through terse shader strings, where each drawing option is a single letter followed by parameters. The string is usually set in init():

1

strcpy(gl.shader, "T0;B11;");   // use texture 0, additive blending

Here T0 selects a texture, B11 sets an additive blend mode, and other letters cover wireframe width, depth testing, culling, colour multipliers and OpenGL texture-coordinate generation. The tutorial presents the blend modes as a direct expression of the OpenGL blending equation, which is a fair summary of the whole language: a thin, music-aware scripting skin over OpenGL.

A second language for the web server

R4’s optional HTTP service used a different, call-expression syntax for pages it served. Kang Seonghoon’s “99 Bottles of Beer” entry is written in it - a single nested expression of strcat, set, get, while, if, hide and newline placed in an HTML file under R4’s wwwroot and rendered on request. It is worth knowing that “R4 script,” as catalogued in the 99-bottles collection, refers to this template facet, while the .r4 scene files use the C-like language above.

Current Relevance

R4 is a closed-source Windows program, and the language cannot be run anywhere else: there is no standalone interpreter, no port and no Docker image. The R4 site is still online and the 1.25 installer, the tutorial and the R4Construct source can still be downloaded, so the language can in principle still be exercised on a Windows machine with a capable graphics card, but nothing about it has changed since about 2010. Its creator moved on to Morphyre and then to Espruino, and the audience that once wrote R4 scenes has largely dispersed. The one piece of R4 that kept a mild afterlife is its web server, which lives on as a teaching example in Metasploit and a fingerprint in vulnerability scanners rather than as a place anyone runs visuals.

Why It Matters

R4 script is a clean example of a whole category of languages that rarely get written up: the embedded scripting language of a single application. It was never meant to be general-purpose, never had a package ecosystem, and never tried to outlive its host. What it did have was a clear job - make a music visualizer’s scenes programmable instead of hard-coded - and a pragmatic design to match, borrowing just enough of C to be learnable and adding exactly the graphics and audio primitives the job required. It is a reminder that for every language with a standards committee there are many like R4 script: small, purpose-built, tied to one program, and interesting precisely because of how tightly form followed function.

Sources

• R4 website, RabidHamster: about.php, main.php, download.php, versions.php (the 0.02-BETA to 1.25 change history), tutorials.php, register.php, screenshot.php (rabidhamster.org/R4/)
• Jussi Harkonen, R4 Programming Tutorial, version 1.0 (rabidhamster.org/R4/R4tut10.pdf; PDF metadata dated 21 February 2005)
• R2/Extreme website, RabidHamster: about.php, index2.php, download.php, shopindex.php (rabidhamster.org/R2/)
• “99 Bottles of Beer,” language entry “R4 script” #762 by Kang Seonghoon (Tokigun), dated 24 June 2005 (“Tested with R4 1v06 and 1v20”)
• Pur3 Ltd, Visualisation (pur3.co.uk/Visualisation); Morphyre, About and Who Are We (morphyre.com), for the R-series history, the 1.4-million-download figure and Morphyre’s September 2009 release
• WinampHeritage, R4_1v20.exe (winampheritage.com), dating that plugin build to 9 February 2004
• Luigi Auriemma, advisory “R4 <= 1.25” (aluigi.org/adv/r4_1-adv.txt, 9 February 2012); CVE-2012-10058 / OSVDB 79007; Rapid7 Metasploit module rabidhamster_r4_log (Exploit-DB 18929, 25 May 2012); Tenable Nessus plugin 61460 “RabidHamster R4 Detection” (9 August 2012)