User Tools

Site Tools


en:tutorials:system:commandline_parameters

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

en:tutorials:system:commandline_parameters [2020/05/15 20:04 (13 days ago)] (current)
sausage created
Line 1: Line 1:
 +====== Commandline Parameters for your game or application ======
  
 +The orxParam module is provided to make handling commandline parameters easier in your game or app. In this tutorial, we'll add a commandline parameter, and a handler for it.
 +
 +To begin, ''​init''​ up a new project that will be used as the basis for this tutorial with: [[en:​tutorials:​creating_your_own_project|Creating your own Orx-based Project using '​init'​]]
 +
 +Now that you have a project which compiles, and runs, let's start by looking at what parameters already exist on the demo program. Go to your compiled application'​s bin folder. You'll see something like:
 +
 +  rwxr-xr-x ​  ​MyGamed.exe
 +  rwxr-xr-x ​  ​orx.dll
 +  rwxr-xr-x ​  ​orxp.dll
 +  rwxr-xr-x ​  ​orxd.dll
 +
 +If you execute your game with the ''​-h''​ parameter, ie, ''​MyGame.exe -h'',​ you will receive the following output:
 +
 +  Options:
 +  -c        --config ​                  Loads the specified configuration file.
 +  -v        --version ​                 Prints orx's version.
 +  -h        --help ​                    ​Prints this help. A parameter can be specified to print its complete description (-h <​param>​).
 +
 +These are three built-in commandline parameters from orx.
 +
 +You could also have specified ''​MyGame.exe %%--%%help''​. This is the long format version of the parameter.
 +
 +===== Adding your own =====
 +
 +In this example, we want the user to be able to specify a different screen width on the commandline,​ rather than run in the default resolution set by the application.
 +
 +Add the following to the top of your ''​Init()''​ function:
 +
 +<code c>
 +  orxPARAM stParam = {orxPARAM_KU32_FLAG_NONE,​ "​w",​ "​width",​ "Set the window width",​ "Set the width of your application window",​ &​SetWindowWidthParameter};​
 +
 +  orxParam_Register(&​stParam);​
 +</​code>​
 +
 +A parameter struct is created and then registered for use. The values above are:
 +
 +<WRAP center round box 90%>
 +//​orxPARAM_KU32_FLAG_NONE//​ - No special behaviour for our param. See [[https://​github.com/​orx/​orx/​blob/​master/​code/​include/​main/​orxParam.h#​L53|orxParam.h]] for options.
 +
 +//"​w"//​ - the short format parameter letter chosen. This means ''​-w''​ on the commandline.
 +
 +//"​width"//​ - this is the long format commandline parameter. The user can say: ''​%%--%%width''​ instead of ''​-w''​.
 +
 +//"Set the window width"//​ - Short format help. This is shown with ''​-h''​.
 +
 +//"Set the width of your application window"//​ - Long format help shown with: ''​-h width''​.
 +
 +//&​SetWindowWidthParameter//​ - address of the handler function that will run if the parameter is used on the commandline.
 +</​WRAP>​
 +
 +
 +The ''​SetWindowWidthParameter''​ function hasn't been created yet, so that's next:
 +
 +<code c>
 +static orxSTATUS orxFASTCALL SetWindowWidthParameter(orxU32 _u32ParamCount,​ const orxSTRING _azParams[]){
 +
 + //At least two params expected for width: the -w and the value
 + if (_u32ParamCount > 1) {
 + orxLOG("​At least two params found."​);​
 + }
 +
 + int count;
 + for (count = 0; count < _u32ParamCount;​ count++){
 + orxLOG("​Parameter:​ %s", _azParams[count]);​
 + }
 +
 + return orxSTATUS_SUCCESS;​
 +}
 +</​code>​
 +
 +The above function will only be called if either a long or short formatted parameter is passed to the application,​ ''​MyGame.exe -w 640''​ or ''​MyGame.exe %%--%%width 640''​.
 +
 +In the function above, at least two params are expected ''​-w''​ and ''​640''​ or whatever value the user wishes to pass in to change the screen size.
 +
 +And finally, the params are looped over and printed out. The actual changing of the screen size can be left as an exercise for the reader.
 +
 +Compile the project and then run it again with ''​MyGame.exe -h''​. Hopefully you should see the new parameter in the available list:
 +
 +  Options:
 +  -c        --config ​                  Loads the specified configuration file.
 +  -w        --width ​                   Set the window wdth
 +  -v        --version ​                 Prints orx's version.
 +  -h        --help ​                    ​Prints this help. A parameter can be specified to print its complete description (-h <​param>​).
 +
 +That's pretty cool. The short and long parameter names are shown, and the short help text. To get the long help, you can type: ''​MyGame.exe -h width'':​
 +
 +  Options:
 +  -w --width ​             Set the width of your application window
 +
 +The short and long parameter names are shown and the long format help is displayed.
 +
 +===== More information =====
 +
 +You can see more examples of orxParam in use in the orxCrypt and orxFontGen [[https://​github.com/​orx/​orx/​tree/​master/​tools|tools]].
en/tutorials/system/commandline_parameters.txt ยท Last modified: 2020/05/15 20:04 (13 days ago) by sausage