JurassicParkTrespasser/jp2_pc/README.md

Getting started with OpenTrespasser

General build requirements

Visual Studio 2019 with the C++ Desktop Development workload is required. That includes the C++ compiler and the Windows SDK. You will also need the packages for MFC and ATL libraries.

All other libraries and tools are provided in this repository, either directly or from Git submodules.

You should install the game Trespasser before starting development on OpenTrespasser, so that the game directory can be autodetected.

Generating the VS solution with CMake

The project configuration and build instructions are written in a CMake script.

It is recommended that you generate a VS solution and VS projects and work with these generated files. To do this, run the script Generate-VS2019-x86.cmd, the solution and project files will be generated under Build\cmake-x86.

If you want more control over CMake, then you can also run CMake-GUI with the launch script Start-CMake-GUI.cmd.

You can regenerate the solution with CMake while it is still open in VS. In that case, VS will ask if you want to reload the solution, which you should do.

VS2019 also has built-in support for CMake projects (if you install the package for that), but this has not been tested yet with OpenTrespasser.

Project configurations

OpenTrespasser knows three project configurations:

• Debug: Compiler optimizations are disabled, runtime checks are enabled. All debugging code is enabled.
• Release: Compiler optimizations are enabled, runtime checks are reduced to default. Some, but not all, debugging code is disabled.
• Final: Same as Release, but all debugging code is disabled.

Note that debug symbols (PDBs) are generated in all three configurations, so using the debugger is always possible.

Execution and debugging

The game executable trespass.exe needs to be run in the Trespasser game directory, usually found in the C:\Program Files (x86)\... path. If a Trespasser installation is detected by CMake, then the Trespasser directory is automatically set to be the working directory for debug execution in VS. This means that you can start the game directly from VS.

Also the built trespass.exe is automatically copied to the Trespasser directory after each build.

Depending on your system configuration, a program running in the Trespasser directory might require elevated rights to write files in that directory. It is recommended that you start VS with admin rights (see below). You should also configure the program to start with admin rights directly, via the compatibility settings.

16bit color depth mode

The renderer only supports 16bit color depth. Adding 32bit support is an open issue.

Running the game with 32bit color depth is possible, but the graphics are faulty and it will inevitably crash after a few minutes. Some apps like GUIApp completely refuse to start in 32bit color depth mode.

We do not know how to make VS start a program in 16bit color depth mode. Perhaps it can be done by starting VS with 16bit color depth, but that would be very inconvenient.

The recommended procedure for using 16bit color depth is this:

• Open the executable's compatiblity settings. Open its file properties and go to the compatibility tab.
• Set the color mode to 16bit.
• Start the program.
• If you need the debugger, attach it manually as described below.

Attaching the debugger manually

You can use the VS Debugger without starting a program from VS. In the Debug menu in the main menu bar, there is a command to attach to a running process. If you attached the debugger once, another command is added to the Debug menu to reattach it, so you don't have to reselect the process.

When starting Trespasser, a warning message might pop up, telling you that your graphics driver is not certified for DirectDraw. It is highly recommended that you do not disable that message. The moment that warning is on display is an excellent opportunity to manually attach the debugger.

Output of debug information

In any normal Win32 GUI program, including the Trespasser game, output to console via std::cout and std::cerr does not work because there is no console. However, Windows offers a special debug output channel, which can be viewed in the Output window in Visual Studio. Trespasser gives convenient access to that channel with the global output stream dout (declared in Lib/Sys/DebugConsole.hpp), which can be used just like std::cout. Note that all output to dout is discarded in Final builds.

Trespasser also supports other forms of debug output, including log files and writing text directly to the game screen, as demonstrated by the bones cheat.

General Tips and Troubleshooting

• Launch Visual Studio with admin rights. Just open the context menu (right-click) for its entry in the start menu and select Run as Admin. Trespasser wants to write files to its own directory under C:\Program Files (x86)\..., and that requires elevated rights on modern Windows configurations. By launching VS with admin rights, it can launch Trespasser with elevated rights as well.

• If you want to make a new tool with the Trespasser code and use MFC/AFX in your project (like the GUIApp), then add this line before you include the MFC headers (i.e. in stdafx.h or pch.h):

  • #define DIRECT3D_VERSION 0x0700

  • The old Direct3D code in the Windows SDK headers is only activated if your project is based on Direct3D 7.0 or lower. In modern Windows SDKs, the MFC headers include the stuff of newer Direct3D versions by default.

• If you get the error The command "setlocal during the build, that means something went wrong in the postbuild step which is supposed to copy the newly built trespass.exe to the Trespasser directory.

  • Ensure that VS is started with Admin rights (see above)
  • If the problem persists, disable the postbuild step.
    • To disable it in VS, open the project settings for trespass, go to Build Events and remove the postbuild command. Note that it will be added again when the solution is regenerated by CMake.
    • To disable the postbuild step in CMake, regenerate the solution, but set the CMake variable USE_TRESPASSER_DIRECTORY to FALSE. That can be easily done with the CMake GUI.