Running the Engine

The development version of Gamestudio's engine - acknex.dll - is located in the Gamestudio folder. There's also a small starter program, acknex.exe, that activates the engine and passes the command line to it. It can be used to start the engine directly with a level, model, movie or script, by giving the following command:

c:\program files\gstudio7\acknex.exe filename [options]

The file name is the name of the application - normally either a script, or a model or level file to view or walk through. The engine will change the current directory to the folder where the application is located, compile it if it is a script, and start it. If no file name is given, the engine will change the current directory to its own folder. For quick starting the engine without SED or WED, use the Windows command line, or create a windows shortcut and assign the above command line to it.

After starting, the engine displays a startup panel with its A7 / lite-C logo for two seconds, then starts the application.  P  The logo display can be suppressed either with the -nwnd command line option (see below), or with a Starter Window Definition (wdf file) in the work folder. In both cases the two seconds delay are also skipped and the application is immediately started.

Supported Applications

The engine can start the following file types : uncompiled scripts (*.c or *.wdl), compiled scripts (*.exe), resources (*.wrs), models (*.x, *.mdl), levels or terrain (*.wmb, *.hmp), sky (*+2.tga, *+6.tga, *+6.dds), sprites (*.bmp, *.pcx, *.tga, *.dds), and movies (*.avi, *.mpg, *.wmv).

Compiled scripts are started directly. Uncompiled scripts are compiled on the fly, then started. Compiling is very fast, and normally takes only a few seconds.

A7.20 Before starting a compiled script (*.exe), it is compared with its uncompiled version (*.c) with the same name. If the compiled exe exists and is newer than the .c file, the engine starts it; otherwise the .c script is compiled, saved, and started. This speeds up the startup process by skipping the script compiling when the script is not changed. Note that #define statements are not evaluated anymore in a compiled program, so make sure that paths or other project settings are contained in a .wdl file (f.i. with a PATH statement).

Alternatively, you can directly start up a resource file (wrs), a level (wmb), a model (mdl), a sprite or sky image (bmp, tga, pcx, dds), or a movie (avi, mpg, wmv). In this case the engine will act as a viewer for that file, running the script include\viewer.c. When using the engine as model viewer, the model is set to the player pointer. This way entity properties can be changed, and entity functions can be called after pressing Tab.

The engine can be started multiple times on the same PC in window mode. Different parameters can be passed to every engine instance by the -d command line option (see below). They can be used, for instance, to open engine windows at different positions of the desktop. Each engine instance can communicate with each other through multiplayer commands. Thus, having several engine instances running on the same PC is very useful for testing a multiplayer configuration. Another possibility is using a multi monitor system for a flight or vehicle simulation with several monitors representing different views. Every view can be rendered by an engine instance that opens a borderless window at a desktop position that covers a single monitor. Because the engine makes no difference at all between several instances running on the same PC, or several instances running on several PCs on a network, the single PC can be replaced by a PC network with almost no changes of the script.

Engine Requirements

The acknex.dll engine runs under any Windows version that supports DirectX 9 or above. Depending on the application, it requires two DLLs that must be found either in the Windows\system32 folder, or directly in the application folder:

The d3dx9_42.dll is automatically added to all applications on publishing. The d3dcompiler_42.dll is automatically added when the shader library (mtlFX.c) is used by the application. This way your application runs also on PCs with an older version of DirectX 9. Make sure that those two dlls are present on the target machine when they are needed. If they are missing, your end users have to install the latest DirectX version for running the engine.

Other DLL plugins may be required by your application. On startup, the engine scans for DLL plugins in the current folder and in the PLUGINDIR folder (the published version only scans PLUGINDIR). This can lead to a slow start when the folders contain lots of DLLs that are no engine plugins - for instance, when the engine is used as a screensaver and started from the Windows folder. If a DLL crashes on opening, the engine crashes also. Thus make sure that PLUGINDIR is set to a folder that only contains engine plugin DLLs - or set it to NULL for preventing the published version from scanning plugins at all. A screensaver example can be found in the samples folder.

Acknex.exe and acknex.dll are part of the development system and must not be given away or copied elsewhere. For distribution of a game, the WED and SED PUBLISH functions will create a distribution version of the engine.

Command line options

Various engine modes can be activated through command line options. User defined command line options can be evaluated by the engine through the command_str string. For setting command line options when starting the engine in SED or WED, just enter the options in the command line field in SED Preferences, or in WED's engine startup dialog. In a published executable, command line options can be given through a shortcut or a batch file - all programm installation packages offer such possibilities. Command line options can also be automatically set in the startup window  P . The following command line options are used by the engine:

-exe  LC 

Compiles the .c code to a binary .exe file in the project folder (not supported by the free version). Exe files don't need to be compiled and thus start faster than .c files. For publishing an executable in Pure Mode, the exe file must be compiled by the Publish process in order to create an engine DLL. In Legacy mode however, the exe file does not use the engine DLL and is ready to run stand alone. When an .exe file is given in the command line, the engine automatically determines from the file date whether to run the original .c script or the compiled .exe file.

-fxo  P  A8

Compiles all used .fx effect files to .fxo files in the project folder . Compiled effects can greatly reduce level loading and material creation time. Only assigned effects are compiled, unused effects are not compiled. The engine automatically determines from the file date whether to load the original .fx file or the compiled .fxo file.

-nwnd  P 

Suppresses the startup window and the start delay. Useful if the engine is started by another program.

-mon number  P  A7.20

In a multi monitor systen, uses the monitor with the given number (1,2,3,...) for fullscreen display, instead of the primary monitor. For using several monitors at the same time, start the main application in server mode (-sv, see below) and start one client application per monitor (-cl -mon).

-nc  P 

Prevents the engine from checking itself for possible virus or hacker tampering at game start. This way, the EXE can be 'wrapped' into another program for using the registration or unlock feature of some distribution channels. 

-cc

Prevents the engine from executing the script. Only the syntax is checked and possible errors are indicated. Often used in combination with -exe for compiling an executable without executing it.

-eq A7.71

Terminates the engine when a syntax error in the lite-C script is found, without waiting until the user hits a key. The error message is printed into the file "ackerr.txt" in the work folder.

-d name[=value]

Under lite-C, sets the variable name to 1 or to the given value (if any) at start of the script, ignoring the predefined value of the variable. This way, arbitrary game options, like starting screen resolution, difficulty grade etc., can be set via the command line. Note that there must be just a '=' and no spaces between name and value in the command line.
Under the old C-Script language, defines the given name for further evaluation in the script through ifdef. This has the same effect as giving define name; or define name,value; within the script.

-diag

Writes diagnostic messages into a file in the current folder. In server mode (-sv ) the filename is acklog_sv.txt; in client mode (-cl ) the filename is acklog_cl.txt; otherwise it's acklog.txt. When starting in dedicated server mode (-sv), the -diag output is additionally printed into the server console window. This way it's possible to observe on the server which clients connect or leave, and what's happening in the game. Write access rights to the current folder are required; under Vista or above, the engine or application can be run as administrator for writing into a program folder.

-dir name

Gives the default folder for saving games and screenshots; will initialize the save_dir string to the give folder name.

-emu

Enables vertex shader emulation on 3D cards without shader hardware, like GeForce1. Vertex shader emulation deactivates hardware vertex processing and thus can reduce the frame rate remarkably, even if no vertex shader is used. Some render or texture stage modes, like CameraSpaceReflectionVector, as well as pixel shaders are not available in vertex shader emulation mode and lead to an error message when used in effect scripts. Therefore vertex shader emulation is used mostly for testing purposes, and is normally not recommended for released games.

-nj

Disables joysticks and 3D navigation devices.

-nm

Disables the mouse.

-ns

Prevents playing sounds, and does not open the DirectSound device. No sound files will be loaded. Media files are still played.

-nv  P 

Prevents rendering and does not open the DirectX Graphics device.

-nx number

Size of the nexus in megabytes. The nexus is a contiguous virtual memory area that the engine allocates at startup for caching entity files and level textures and geometry. It speeds up level loading and prevents that the game suddenly aborts at runtime when memory is running low. The nexus size depends on the size of the biggest level of the game. The bigger the nexus, the bigger levels can be rendered - but the more virtual memory is allocated at startup .

When you set the nexus in Map Properties, WED uses the -nx command line option to transfer the nexus size to the engine. The default value for the nexus is 40 megabytes. The maximum value is limited by the Virtual Memory Setting of the Windows OS, minus around 500...1000 MB that should remain free for the operating system. The current nexus requirement is indicated in the statistics panel and can be read from the nexus variable. The recommended maximum nexus value for commercial games is 200. When setting higher values, you should be aware that several Windows subsystems - including DirectX - tend to crash without error message when the virtual memory is running low.

If the nexus size is exceeded, the engine will allocate additional memory from the PC's virtual memory pool. If the virtual memory is also used up, the application will issue an error message and terminate. The level_mark and level_free functions only work when the nexus is not exceeded. In engines older than A7, exceeding the nexus size will produce a "Nexus too small" error message. The engine must then be restarted with a nexus size higher than that you've used before (e.g. -nx 80 for 80 MB nexus size).

-ip name

The server name, the server's machine name, domain name or IP address when starting a client in multiplayer mode. Example:

acknex office.c -cl -ip 169.254.73.28

connects to the server with the given IP address on the network or internet. The given name or address is available during gameplay in the predefined server_name string. If this command line option is not given, the server will be searched on the local network.

-pl name

By this option an individual name can be given to each client in a multiplayer system (up to 16 characters). Otherwise the engine will generate a client name. During gameplay the name is available in the player_name string.

-port number

Through this command line option, a port address for client/server communication can be given. Valid ports are in the range 2300..2400. If no port is given, a default port address is assigned.

-sn name

Through this command line option the session name can be given when starting a server or a client in multiplayer mode. The default session name is the name of the main script file without extension, e.g. "office" for starting the office.wdl. The given name or address is available during gameplay in the predefined session_name string.

-cl  C 

Joins to a multiplayer session in client mode. If no server or no session is found, the engine automatically starts in non-multiplayer mode.

-sv  C 

Starts a new multiplayer session in server mode. When used in combination with -cl, the server is a client at the same time. Stand alone server mode is only supported by the Professional Edition.

-w3d

Will enforce weak D3D mode without using the stencil buffer. This way old 3D cards without T&L or stencil support can be forced to run. The graphics quality is inferior in this mode.

-wnd

Will enforce window mode even if default fullscreen mode is defined. As long as you haven't redefined the on_enter function, you can always switch between window and fullscreen mode by [Alt-Enter].

 

► latest version online