Connecting to the Game: accessing the DDE interface with 3 lines of code. (Tutorial)

We've been studying a lot of stuff lately, most of it involving running CAOS commands against C1 and C2 games.
C3 has a convenient built-in CAOS console, and various third party tools also propose that feature for C1 and C2.

But how would you go about implementing this kind of connectivity inside your own programs?
The simplest way to connect to a running C1 or C2 game is through the DDE interface (Dynamic Data Exchange). Also it REALLY is simple even if you barely know anything about programming, so this might be worth checking out.If you never programmed anything and don't have any development tools handy, you could initiate a DDE connection even from inside an Excel macro using VBA.Also the C1 and C2 DDE interfaces being strictly identical, you'll be writing code only once, and be able to use it in both games right now, without any change.

By sending the game some basic CAOS commands and reading their results you can reproduce all of the game functionalities and then some more: reading a Norn's needs and chemicals levels in realtime, selecting Norns and Grendels, carrying them, monitoring their brains,etc...

This time I show you a very quick overview to get you started in pumping CAOS in and out the C1 and C2 games.More advanced use cases or details will come in futher posts.
 

 

 

So what is DDE?

DDE stands for Dynamic Data Exchange.It's an old (and in fact deprecated) way to make different processes (executables) talk to each other when run on the same machine.

It has been since superseded by other communications methods such as COM/OLE  or direct shared memory interfaces (such as those used in C3/DS for accomplishing the same task).

We will be covering DDE here as it really is the easiest way to connect to C1 and C2 games.
Although it is worth noting that both games also support a couple OLE interfaces, which are slightly more intricate to use but offer advanced functions such as actively notifying your application of events happening in game (such as Norns entering and leaving the game for example, which is not supported over DDE).

Ole interfaces are also what is used by all C1 and C2 kits/applets (which are external applications after all) to interact with the game.
In an upcoming article we will also be covering how to make a proper applet from scratch and integrate it with the game's toolbar using the OLE interface.
But let's get back on DDE tracks for now:

The DDE communication model:

The DDE communication process is based on a server/client model.
The server (the creatures game) announces to the system that it is open to receive and handle requests through DDE.Doing so it registers as an arbitrary name.This is called the "Application", and both C1 and C2 ask to be called "Vivarium"

The server application will accept various channels of communication.To distinguish between requests originating from various programs, each client uses a different name when connecting the DDE service.
The couple Application + identifier is called the "LinkTopic", and you can pick any valid Link topic for your application in the form : "Vivarium|Whatever"

Finally the server application can offer various services under an arbitrary set of names.No standard exist as to what names should be use or what they should do.The name of such a service is called the DDE "Item".
Both C1 and C2 serve an unique DDE Item called "Macro"; whose net effect is of receiving a CAOS script from the client and sending it back the script output.(The lack of standardisation or ability to ask the service to list offered methods is one of the reasons why the DDE model was abandoned)

A DDE communication happens when a client decides to connect to a DDE service.
It simply provides the operating system the "LinkTopic", it wants to use, along with the "Item" it is interested in, and it also provides optional data as an input for the service.
In our case, our tools will contact the "Vivarium|Myapp" LinkTopic, requesting the "Macro" Item, and passing it arbitrary CAOS script strings as a parameter.

This is all there is to really understanding the DDE basics, and putting this into practice is even easier.

Running an actual DDE communication in VB:

Since the DDE model was deprecated, it's not as easily usable in modern development tools such as .Net as it used to be.
To keep things at their simplest we will therefore use a Visual studio version anterior to the .Net craze, such as visual basic 5 or 6.
If you can't get a hold of such a development environment, the exact same possibilities are offered in the VBA macro interface of any word or excel program from a similar time period.

In those environments, setting up a DDE link was an easy 4.5 step process:

• Create a new VB project, add a textbox (called text1 by default), and a button (called command1 by default)
• If you chose to order the proprieties window "by category", you can easily set the text1 textbox properties in the "DDE" category as:

• LinkTopic set to "Vivarium|SLKtestApp" where SLKtestapp is any name you choose.
• LinkItem set to "Macro" , this is mandatory.
• Don't set LinkMode yet as this would already try a connection even without your application running and would mess up further results.
•  Your app should now look like this:
   
  
  

•  While you're at it, clear the text1's "text" property to empty the box, and set the Command1's "Caption" property to "Run command" to make it look nicer.

•  Now double click on an empty area of the form, this should pop up the code editor in the form1's "Form_Load" event. Any code put there will be executed at the application runtime.Here is the good place to specify our DDE ling link type (Manual means that we will be actively querying the DDE service, and that it shouldn't send us anything without us asking for it first). Set this section's code as :

Private Sub Form_Load()
Text1.LinkMode = 2 ' 2 is "manual"
End Sub

•  The last step is to define the button's action, double click on it and set its "Command1_Click()" event to look like : 

Private Sub Command1_Click()
Text1.LinkPoke 'Say "we're ready to recieve some data"
Text1.LinkRequest 'Send our command and read response back
End Sub


This is it ! you now have a fully working C1/C2 CAOS console.Wasn't that hard was it ?

Don't forget to run the game first, you can then run your application by pressing <F5>.
Enter any CAOS command in the text box and hit the Run command  button, you should get the expected results, with the command's execution result now filling your textbox :

You can now further tune your application to be more user friendly and maybe also add some error handling (as you will probably get a couple nasty errors as soon as you abruptly close the game with your console still running.)

If you don't know anything about CAOS yet, have a look at my small CAOS snippets collection, it contains a batch of readily runnable examples performing common tasks you can use for your tests.

This might be a good place to notice that C1 (and c2 to a slightly lesser extent) are really picky about your CAOS script syntax, forget the slightest space, comma or such, and the game will most likely instantly crash.
Even if it only gives you an error message and continues to run, I recommend you close and rerun the game before sending any further command as :

• The game will most likely crash at your next command anyway
• Even if it seems to be fine, it will most likely crash in a couple minutes anyway

Here are some common use commands you might find useful for your early tests:

Get current creature's name:
dde: getb cnam

Select the Grendel:
enum 4 2 0,sys: camt,setv norn targ,next

Get a bunch of usefull stats on all Norns at once:
dde: getb ovvd

This returns a list of parameters delimited by pipes "|' and is interpreted as such:
Name|Moniker|Sex|Age|Pregnancy|Life Force|Medical condition|Current Room|Xposition|Yposition.

Pause the game:
sys: cmnd 32838

Resume the game
sys: cmnd 32837

Toggle infinite scrolling :
sys: cmnd 32774

Carry current item/Norn in the hand:
edit

For other commands see the CAOS snippets reference or wait patiently for a full CAOS tutorial.
You can reproduce any kit's or third party applet functionality inside your own programs by feeding the game the appropriate CAOS script and then exploiting its response, for example by using the "driv" command you could mimic the  health kit status window:

Further stuff:

Here is some other DDE information I will be covering in upcoming articles:

• By using VB or VBA, we've occulted most of the complexity behind setting up a DDE connexion.There are a couple function calls that are used behind the scene for operating the DDE magic, these can be used from any programming language and I will show you how it is done at least in python sometime soon.
•  DDE links were once a very common way of communication.Even without using VBA, Both Excel and OpenOffice offer a simplified syntax to tie a cell's value to the result of a DDE command.This opens up the potential for having Excel spreadsheets displaying and graphing realtime Norn data, think about how awesome this could be :)

Meanwhile, don't forget to have a look at the awesome Chris Double site which is the only online source I've found talking about the various creatures programming interfaces in enough detail to be usable.
It has examples, explanations and code to access the various C1,2,3 interfaces from different programming languages.