Quake DeveLS - Perl Interface

Author: Chris Hilton
Difficulty: Medium

Foreword by SumFuka

If you are a Perl virgin, you may be wondering what the hell Perl actually is. Well, it's a high level language that is used mainly in website programming. You've been to all those shopping websites where you can 'buy' things and put them in your 'shopping trolley' ? Those websites are probably powered by programs written in Perl. You can use Perl for lots of things, but it is ideally suited to string processing. The Perl example Chris has written for this tutorial simply capitalized the first letter of each word in a string, and turns the string green (by playing with ASCII codes). Other applcations ? Sure ! A frag log for a server would be a good example. Or a password file. You could retrieve a user's password with one line of Perl code ... rather than coding 30 lines of C code to open the file, read it line by line, look for the user name... etc etc. Enjoy. [/SumFuka].

Let's Do It...

Someone had to do it! In my continuing quest to become a Perl guru, let me tell you about embedding Perl in your Quake 2 DLL. I've implemented the calls to Perl in what I hope is a simple API - use it or modify it as you prefer.

Note: This is not a tutorial on Perl! Get the "Learning Perl" (http://www.ora.com/catalog/lperl2/index.html) and "Programming Perl" (http://www.ora.com/catalog/pperl2/index.html) books from O'Reilly and Associates. These are THE books on Perl. At least basic familiarity with programming Perl is assumed for the rest of this tutorial.

First, you'll need Perl installed on your system. If using Windows, you must download Gurusamy Sarathy's binary version of Perl for Win32 at ftp://ftp.digital.com/pub/plan/perl/CPAN/ports/win32/Standard/x86. ActiveState's build of Perl for Win32 is great, but embedding Perl with their library is vastly different from Unix builds, so we'll use Sarathy's version for maximum portability.

Okay, now that you have Perl installed, let's look at the code for implementing this Perl API.

//
// cch_perlq2.c
//
// Adding a perl interpreter to Quake 2

#include              // from the Perl distribution
#include                // ditto

static PerlInterpreter  *myPerl;

void InitPerl()
{
        char    *argv[] = { "", "perlq2.pl" };
        int             argc = 2;

        myPerl = perl_alloc();
        perl_construct(myPerl);
        perl_parse(myPerl, NULL, argc, argv, NULL);
        perl_run(myPerl);
}

I32 PerlEval(char *string)
{
        return perl_eval_sv(newSVpv(string, 0), G_DISCARD);
}

int GetPerlInt(char *string)
{
        return SvIV(perl_get_sv(string, FALSE));
}

float GetPerlFloat(char *string)
{
        return SvNV(perl_get_sv(string, FALSE));
}

char *GetPerlString(char *string)
{
        STRLEN  length;

        return SvPV(perl_get_sv(string, FALSE), length);
}

void FreePerl()
{
        perl_destruct(myPerl);
        perl_free(myPerl);
}

Actually, most of this code is program independent, so knock yourself out imbedding Perl into all of your programs. :) If the specifics of those functions look overwhelming, don't worry too much about them. Mostly they refer to stuff in the Perl library that you'll never have to bother with because you'll be using these nifty little API functions instead. Let's go over those functions.

InitPerl() sets everything up for us. perl_alloc and perl_construct ready the Perl interpreter. perl_parse will parse the file 'perlq2.pl' which should be located in the current working directory. You should put any Perl functions or other Perl code you want initiated at startup in this file. perl_run actually runs the code so that, at this point, your Perl interpreter should be fully initialized. This should be added to the InitGame() function in g_save.c, I prefer toward the end of the function at about line 190 (+'s indicate lines added).

                InitClientResp (&game.clients[i]);
        }
        globals.num_edicts = game.maxclients+1;
+
+       // CCH: Initialize perl interpreter
+       InitPerl();
 }

PerlEval() is where you will be feeding Perl code to the interpreter. Just call PerlEval() with any string containing Perl code and the interpreter will evaluate it. That's right, any Perl code should work. As the perlembed manpage/documentation says, "Your string can be as long as you wish; it can contain multiple statements; it can employ 'use', 'require', and 'do' to include external Perl files." The world is your oyster. Perl. Get it? Anyway...

The next three GetPerl*() functions are intended to provide an easy interface for retrieving scalar values from the Perl interpreter. If you need the integer equivalent of the scalar value '$time', just use GetPerlInt("time"). Need that as a float, you say? GetPerlFloat("time"). Never mind, you're going to print it out instead? GetPerlString("time"). Time, time, time, see what's become of me...

PerlFree() deallocates the Perl interpreter and frees up the memory. It's always good to clean up after yourself. This should be added to the ShutdownGame() function in g_main.c, at about line 80.

        gi.FreeTags (TAG_LEVEL);
        gi.FreeTags (TAG_GAME);
+
+       // CCH: Free the perl interpreter
+       FreePerl();
 }

Finally, to use all these functions, you'll have to add the following to g_local.h.

+// CCH: PerlQ2 includes & functions
+#include      // from the Perl distribution
+
+void InitPerl();
+I32 PerlEval(char *string);
+int GetPerlInt(char *string);
+float GetPerlFloat(char *string);
+char *GetPerlString(char *string);
+void FreePerl();

"handy.h" is included to resolve the I32 reference that PerlEval() returns. You'll also need to set your compiling options so that the Perl library, perl.lib, is included in your project and the include files can be found. In MSVC 5.0, this entails going to Tools->Options, selecting the Directories tab, and adding your Perl CORE directory (probably "C:\Perl\Lib\CORE") to the Include and Library directories. You should also open your Project, go to Project->Settings, select "All Configurations" in the "Settings For:" field, select the Link tab, then add 'perl.lib' to the Object/library modules. Hopefully, those of you using other compilers can figure out your own implementation, but I recommend reading the perlembed manpage/documentation if you run into trouble.

Okay, we know all the details now, let's try an example. Here's a perlq2.pl to put in your Quake 2 directory.

#
# perlq2.pl
#

sub CapAndColor {
        my($string) = @_;

        $string =~ s/\b\w/pack("c",ord(uc($&))|128)/eg;
        return($string);
}

This file contains one Perl function called CapAndColor(). It takes a string as its first argument, capitalizes the first letter of every word and sets that letter to print in green text in Quake 2. It then returns this new string.

Now, we need a way to call this Perl code. After adding all the appropriate code from above for setting up the Perl interpreter, we add a new command to g_cmds.c.

+/*
+=================
+Cmd_JAPH_f
+CCH: function for JAPH command
+=================
+*/
+void Cmd_JAPH_f (edict_t *ent)
+{
+       char    *japh = "just another perl hacker";
+       char    perlCommand[64];
+
+       sprintf(perlCommand, "$return = &CapAndColor('%s');", japh);
+       PerlEval(perlCommand);
+       gi.centerprintf(ent, "%s\n", GetPerlString("return"));
+}

This function simply sprintf's our japh variable and the Perl code we want to call into a temporary perlCommand buffer. Notice how we have '$return' receive the return value from &CapAndColor(); we could call &CapAndColor() directly, but we'd have no way to get to the result! After having PerlEval() evaluate our command, we then use GetPerlString() to retrieve the result of the &CapAndColor() call and centerprint it to the player.

One last tidbit we need is a way to call this command function, so we add the following to ClientCommand() in g_cmds.c.

                Cmd_Kill_f (ent);
        else if (Q_stricmp (cmd, "putaway") == 0)
                Cmd_PutAway_f (ent);
+       
+       // CCH: japh command
+       else if (Q_stricmp (cmd, "japh") == 0)
+               Cmd_JAPH_f (ent);
+
        else if (Q_stricmp (cmd, "wave") == 0)
                Cmd_Wave_f (ent);
        else if (Q_stricmp (cmd, "gameversion") == 0)

Now, you should be able to compile this up, load quake2 with your new gamex86.dll, and type 'cmd japh' at the console and see 'Just Another Perl Hacker' centerprinted on your screen with J, A, P, and H in green, the rest of the text in white. For you paranoid types and Intel lawyers (I repeat myself?), this is not 'hacker' in the media sense. Just thought I'd mention that for Randal's sake.

Anyway, I think this is a pretty simple but fairly powerful API to Perl (it seems like it's hard NOT to do something powerful with Perl). If anyone finds this useful and would like to see me work more on it (like, oh, adding ERROR HANDLING, maybe, figuring out what PerlEval() is returning...), drop me a line so I'll know there's interest. Speaking of error handling, at this point, there isn't any, so try running your Perl scripts from the command line first if you're having problems. Also, get Perl running with a simple script (like the above example) first before you go wild with your 2000 lines of Perl code, okay?

Full source, patch file, and DLL at http://www.jump.net/~dctank.

Chris Hilton .

This site, and all content and graphics displayed on it,
are ©opyrighted to the Quake DeveLS team. All rights received.
Got a suggestion? Comment? Question? Hate mail? Send it to us!
Oh yeah, this site is best viewed in 16 Bit or higher, with the resolution on 800*600.
Thanks to Planet Quake for their great help and support with hosting.
Best viewed with Netscape 4