Adventure Game Studio

---

---

When I was tinkering with the php source for some project yesterday I thought, why not :D Well yes, php is foremost a server-side scripting language, but I've used it for all sort of things in the past. It's quite good for messing around without being washed down with complex libraries. I don't know a purpose for it yet but I think others will. It's not recommended to use it for high-end stuff. Well, that said, here goes:


Installing
Copy 'agsphp.dll' to the same path as the AGS editor. Copy the other files (phpts5.dll and php.ini) to your debug and build directory.

License
As far as I understood the php license (I'm not a lawyer) you are free to ship these files (even in commercial projects) as long as you include the php license (which can be found in license.txt) to it.

Issues
- if it complains about 'msvcr100.dll' you need to install service pack 3. If you're worried players will have problems with this you can include the dll to you project.

Documentation

There are two ways in which php can be invoked:
 - evaluation of a string
 - execution of a script file

Php on its turn can interact with AGS in two ways:
 - send input through its output stream
 - raise an event within AGS

To optimize the interaction between AGS and PHP it is also possible to read and write (global) variables from/to PHP.

Functions:

bool   ExecPHPScript(String file)

   Executes a php script file. The file can be located in the same directory 
   as the executable, or you could specify a path. It is even possible to 
   specify a webaddress as source, though I've not tested it I know PHP can 
   do this.
   Returns true if file was loaded, false otherwise (file no found)


void   EvalPHPString(String code)
int    EvalPHPStringInt(String code)
float  EvalPHPStringFlt(String code)
String EvalPHPStringStr(String code)

   Evaluates 'code' and returns the indicated value type. If a error 
   occured, a empty value is returned.
   Note: Always use EvalPHPString is you are not returning a value.

 
void   SetPHPValStr(String name, String value)
void   SetPHPValInt(String name, int value)
void   SetPHPValFlt(String name, float value)

   Sets 'value' to a global variable '$name' of the indicated value type.

  
String GetPHPValStr(String name)
int    GetPHPValInt(String name)
float  GetPHPValFlt(String name)

   Returns the value of a global variable '$name' of the indicated value 
   type.


Events:

void   on_php_input(String input)         /* global script */

   Raised when something is printed/echoed from php.


void   on_php_error(String msg)           /* global script */

   Raised when an error occurs in a script file or eval string.
   'msg' contains the full error message.
   (better to not have to use this :D)

void   on_php_call(int code, String msg)  /* global/room script */

   Raised when php calls (see below)
   PHP can specify a number and a string for whatever purpose you need.


PHP functions:

function ags_call($code, $msg)
function ags_call_room($code, $msg)

   These two function can be called from everywhere in the php scripts/code. 
   ags_call will raise the event in the global script
   ags_call_room will raise it in... well erm room scripts :D


Well thats it!

Have fun!

Interesting!
I will definitely try this one day and see if I can use it for something cool :).