ENIGMA Forums

Sharing is caring => Tips, Tutorials, Examples => Topic started by: time-killer-games on December 20, 2020, 03:55:52 pm

Title: Running NGINX Server in GameMaker and ENIGMA
Post by: time-killer-games on December 20, 2020, 03:55:52 pm
Running NGINX Server in GameMaker and ENIGMA

ENIGMA | GM Version: GameMaker Sudio 2.x or later (ENIGMA and GMS 1.4.x too but w/ different string handling)
Target Platform: Windows, (macOS and Linux/Ubuntu need slightly modified instructions)
Links:  CLICK HERE FOR PROCESS INFO'S EXTENSION DOCUMENTATION (https://www.dropbox.com/s/ahbhcsum51he7nb/docs.html?dl=0)
Downloads (Required): NGINX (http://nginx.org/en/download.html), FILE MANAGER (https://marketplace.yoyogames.com/assets/5510/file-manager), PROCESS INFO (https://marketplace.yoyogames.com/assets/9149/process-info)

Introduction:

ENIGMA users can ignore the download links for File Manager and Process Info above. Server and client interaction is very common in games and my Process Info extension allows you to do much more with that. For the time being, these extensions are not available in ENIGMA's main repository. File Manager is virtually the same as the upcoming official support for std::filesystem in ENIGMA, however I have several bells and whistles added in my repository such as the ability to pass environment variables directly to string arguments when in the form of, for example, ${VARIABLE}.

TL;DR ENIGMA users have to install ENIGMA from the instructions on my own repository instead to get the required extensions:

https://github.com/time-killer-games/enigma-dev

Then you may proceed with this tutorial.

Summary:

Someone added me on Discord asking me how to do this with my Execute Shell extension, so I used that as an excuse to educate everyone here on a practical use case for my much more powerful extension called Process Info, hoping more people switch to using that extension instead of my Execute Shell and Evaluate Shell extensions, which are much less powerful and deprecated in favor of Process Info. They are also no longer actively developed and won't receive any feature updates. Use Process Info instead, it has a learning curve that is steeper, but you will learn to appreciate it with time as you learn what it can do.

Here I am explaining how to use Process Info more specifically on the topic of how to properly run your own NGINX server.

Tutorial:

Download NGINX and extract the ZIP archive. Drag and drop all the files in the extracted contents, (if extracted to a new folder, the contents of that folder), into your GameMaker Studio 2.x window to add them as included files for your project to make use of them. Not just the nginx executable, but also the folders it depends on which are also included in the ZIP you extracted. Create a controller object obj_conttroller, create a blank room with a black background, and then drag your controller object from the resource tree into your room. Now your body is ready.

(https://i.kym-cdn.com/entries/icons/original/000/004/161/mybody.jpg)

In the Create Event of your controller object...

General Initialization and copying all your files to where they need to be is the first thing we need to take care of before we can do anything else.

1) First, choose a process index, similar to a resource id like for a sprite or other stuff, but this will represent a unique instance of a running application so we can later get various information from it such as output that would show in the terminal or command prompt if something goes wrong you can further debug it with ease. I chose the variable name to be nginx because that is the name of the executable we are running here, and a value of 0 stored in the variable to uniquely identify the process index:
Code: (gml) [Select]
globalvar nginx; nginx = 0;
2) Next, we create the sandbox directory, using the game_save_id constant, which is a writable directory, the working directory won't always be writable, thus we are using the sandbox directory for that reason alone:
Code: (gml) [Select]
directory_create(game_save_id);
3) Then, copy the included files we have in our project (nginx and its associated files and folders) using my File Manager extension's directory_copy function:
Code: (gml) [Select]
directory_copy(working_directory, game_save_id + "files");
4) We need to set a new working directory to where we copied the included files to, using File Manager's set_working_directory(dname) function, like so:
Code: (gml) [Select]
set_working_directory(game_save_id + "files");and that will set the new working directory to the "files" subdirectory we copied into the sandbox folder game_save_id from the working_directory in step 3. It will also copy everything else the game depends on, not just the included files you previously drag and dropped onto the GameMaker Studio 2 IDE window.

Now we can write a batch file that will run nginx and we will write it directly to our sandbox, (not to be confused with what we set the working _directory to, which is the "files" subfolder within the sandbox folder game_save_id):
Code: (gml) [Select]
f = file_text_open_write(game_save_id + "nginx.bat");
file_text_write_string(f, @'cd "' + working_directory + @'" & "' + working_directory + @'nginx.exe"');
file_text_close(f);

Notice above I also set the working directory of the batch file using the cd command, which is necessary to get this stuff working. Now for the good part; we are going to execute asynchronously an instance of a nginx web server process, but first, please notice I created a temp folder:
Code: (gml) [Select]
directory_create(working_directory + "temp");
process_execute_async(nginx, @'cmd /c @ECHO OFF & "' + game_save_id + @'nginx.bat"');

That temp folder is needed by nginx, otherwise it will complain in the process standard output that the folder doesn't exist. Notice there are two arguments to our process creation function, the second argument is the command itself, not the first. In the second argument we are running the batch file we created earlier found in our sandbox directory game_save_id.

The first argument of process_execute_asnyc(ind, command), on-the-other-hand, should be the global variable we set in the very first step of this tutorial, nginx as the variable's name and zero as its value to represent an index for the specific running application instance, which will be used to get process output for debugging purposes like mentioned earlier. That leads to our next step major step in this tutorial.

Done with Create Event. Now Draw Event / Draw GUI.

Now we are going to draw the process output to our game window in case something went wrong. If you followed this tutorial perfectly as described, no text should be drawn. In the code below you'll see I am setting a custom font named fnt_example, you will either need to create a font yourself that has this name or omit that line completely. The key thing is the text needs to not be cropped when drawn, so make the text small enough it is readable but will still fit in your game window or view-port for easy viewing. If you want to program a camera system to view the output text more power to you but that I won't be covering and it is a lot of unnecessary extra effort. The second line is where we actually draw the process output, should you have messed up following any steps thus far, text will draw and you will need to go back and review this tutorial to debug what the issue is based on what info is drawn.
Code: (gml) [Select]
draw_set_font(fnt_example);
draw_text(0, 0, process_output(nginx));

process_output(ind) will return the process output for the specified process index, that is, the running application process that was started using the exact same process index ind argument. To clear process output when you no longer need it and wish to free memory, call process_clear_out(ind) on the same exact process index value, in this case the value we have stored in the nginx global variable.

Done with Draw Event / Draw GUI. Now for Game End Event.

Now, create a Game End event in your controller object, and give it the following code to execute when triggered:
Code: (gml) [Select]
process_execute(999, @'"' + working_directory + @'nginx.exe" -s stop');
This will cause the nginx server to shut down automatically when you close the game, to prevent it running in the background after you are done with it. Notice I used process_execute(ind, command) which will run synchronously, unlike process_execute_async(ind, command) which is what we used earlier. For the process index ind argument I used 999 as the reserved value to represent this process to make room for other process indexes to be used throughout your program should you ever have the need to run 999 other processes (counting zero) simultaneously, this allows for that many if you count up without skipping a reserved value for each process you create. Though 999 is not required, you may use any ridiculously high number if you wish that is less than ULONG_MAX(=4294967295). The key thing is that every process you have running from your game or application must have a unique index when run and held in memory simultaneously. A process index also can not be negative nor can it have a decimal value.

To free a process index from memory, call process_clear_pid(ind) to get rid of the pid's (process identifer, not the same thing as an index) held in memory, as well as call process_clear_out(ind) to get rid of the process index's standard output strings held in memory.

In other words, for example:
Code: (gml) [Select]
process_clear_pid(nginx);
process_clear_out(nginx);
process_clear_pid(999);
process_clear_out(999);

The above can be put in your Game End event after the process_execute(ind, command) call for general code cleanup.

If you followed everything correctly, you should have the following code in your controller object:

Create Event:
Code: (gml) [Select]
globalvar nginx; nginx = 0;
directory_create(game_save_id);
directory_copy(working_directory, game_save_id + "files");
set_working_directory(game_save_id + "files");
f = file_text_open_write(game_save_id + "nginx.bat");
file_text_write_string(f, @'cd "' + working_directory + @'" & "' + working_directory + @'nginx.exe"');
file_text_close(f);
directory_create(working_directory + "temp");
process_execute_async(nginx, @'cmd /c @ECHO OFF & "' + game_save_id + @'nginx.bat"');
Draw Event (or Draw GUI, either one):
Code: (gml) [Select]
draw_set_font(fnt_example); // optional line
draw_text(0, 0, process_output(nginx));
Game End Event:
Code: (gml) [Select]
process_execute(999, @'"' + working_directory + @'nginx.exe" -s stop');
process_clear_pid(nginx);
process_clear_out(nginx);
process_clear_pid(999);
process_clear_out(999);

Like normal when running the NGINX server executable, it will ask you for permission to access your local network, and which you will need to accept. You can view the server by typing in "localhost" in your favorite internet browser.

Happy Coding!
Samuel