Install TaystJK

This section also covers platform support, builds and versioning and mod compatibility.

Before you start

You need a legal Jedi Academy installation and these files from its GameData/base directory:

assets0.pk3
assets1.pk3
assets2.pk3
assets3.pk3

Download the build for your operating system from the latest TaystJK release. Extract the whole archive; do not copy only the executable, because the renderer and game libraries beside it are also required.

If you also install an older mod, check whether it keeps its native modules inside a PK3. TaystJK does not unpack those modules by default; see mods that package native libraries inside a PK3 before assuming that the mod is incompatible.

Install for your platform

Choose your operating system to see its prerequisites and installation steps. Your selection is saved on this device.

TaystJK_Updater.exe taystjk.x86_64.exe +set fs_cdPath "../JediAcademy"

xattr -dr com.apple.quarantine "/path/to/taystjk.app"

codesign --verify --deep --strict "/path/to/taystjk.app"

sudo apt update
sudo apt install libsdl2-2.0-0 libgl1 libjpeg-turbo8 libpng16-16 zlib1g libstdc++6

# Fedora
sudo dnf install SDL2 libglvnd-glx libjpeg-turbo libpng zlib libstdc++

# Arch Linux
sudo pacman -S sdl2 libglvnd libjpeg-turbo libpng zlib

ldd ./taystjk.x86_64 | grep "not found"

Installing several modded clients

Do not merge every client’s executables and shared libraries into one GameData directory. Different projects, or 32-bit and 64-bit builds of the same project, may ship incompatible SDL2 or OpenAL libraries.

Recommended: one shared asset directory

Keep the retail assets once and give every client its own directory:

MyGames/
├── JediAcademy/
│   └── base/
│       ├── assets0.pk3
│       ├── assets1.pk3
│       ├── assets2.pk3
│       └── assets3.pk3
├── TaystJK/
│   ├── taystjk/
│   │   └── japro-assets.pk3
│   ├── taystjk.x86_64.exe
│   └── run-taystjk.bat
└── AnotherClient/
    ├── another-client files…
    └── run-client.bat

On Windows, put this beside the TaystJK executable as run-taystjk.bat:

@echo off
start "" taystjk.x86_64.exe +set fs_cdPath "../JediAcademy"

Use the executable name that actually appears in your release archive. On Linux, the equivalent launch command is:

./taystjk.x86_64 +set fs_cdPath ../JediAcademy

fs_cdPath supplies the shared retail assets while TaystJK keeps its own executable, libraries, mod directory, and user files separate.

Simpler alternative: copy base

Copy the complete retail base directory into each client’s directory. This uses more disk space, but needs no launch script and keeps each installation self-contained.

Put PK3s that should affect every client in that client’s base directory. Put TaystJK-only content in taystjk/, beside japro-assets.pk3.

Run TaystJK with another client-side mod

The TaystJK executable is the engine. The game, client-game, and UI modules are separate native libraries:

macOS uses the equivalent .dylib files. TaystJK does not currently execute QVM bytecode; both its current module API and the older dllEntry/vmMain API load native libraries. A module must match the operating system and CPU architecture of the TaystJK executable.

Mods that package native libraries inside a PK3

Many older mods put cgame, ui, or jampgame native libraries inside a PK3. TaystJK still mounts the PK3 and reads its assets, but it does not unpack and execute those libraries by default: com_unpackLibraries defaults to 0, and both module loaders only try PK3 unpacking when it is enabled (registration, legacy loader, OpenJK-style loader). This can make an old mod’s assets appear while its custom HUD, menus, or game code does not load.

The preferred fix is to extract the native libraries from the mod’s PK3 and place them beside that PK3 in the mod directory. Keep the PK3 because the mod may still need its maps, menus, shaders, and other assets. For a 32-bit Windows mod, the result commonly looks like this:

japlus/
├── mod-assets.pk3
├── cgamex86.dll
├── uix86.dll
└── jampgamex86.dll

Only extract files from a mod you trust. Native modules are executable code, not passive assets. The names and architecture must match the TaystJK build: an x86.dll from an old mod cannot be loaded by the 64-bit client. Use the 32-bit Windows build for a mod that provides only 32-bit Windows modules, or obtain modules built for your platform and architecture.

On Windows, you can instead opt back into the old unpacking behavior for a trusted mod by setting the cvar at startup:

taystjk.x86.exe +set fs_game japlus +set fs_forcegame japlus +set com_unpackLibraries 1

com_unpackLibraries is an initialization cvar, so put it on the command line rather than changing it after launch. This fallback is implemented on Windows. It does not extract ordinary .so or .dylib modules on Linux or macOS, so install those as loose native libraries (Windows unpacker, Unix behavior).

What fs_forcegame does

On a normal client, fs_forcegame defaults to taystjk. This keeps TaystJK’s directory at the highest filesystem priority when a server supplies a different fs_game, and keeps configs, demos, screenshots, and other generated files under taystjk/. A server cannot change fs_forcegame.

The default is therefore appropriate when you want TaystJK’s client-side files and settings while joining servers that run JA+, JA++, jaPRO, or another server-side mod. You can state it explicitly in a shortcut or launch script:

taystjk.x86_64.exe +set fs_forcegame taystjk

Use the executable name for your platform. Do not add fs_game merely to join a server; the server sends its own game directory during connection.

Native libraries are a separate concern: when a matching loose library exists in the server-selected fs_game directory, the engine tries that library before the copy in taystjk/. Keep other mods’ native client libraries out of a clean TaystJK installation unless you intend to load them.

To deliberately use another mod’s client-side libraries and assets, install them in that mod’s directory and select it at startup. For example, JA++ uses japlus/ for compatibility with JA+:

taystjk.x86_64.exe +set fs_game japlus +set fs_forcegame japlus

Setting both values loads the mod from the beginning, including a custom UI, and prevents a later server-provided fs_game from changing the directory used for files and generated output. To return to the normal TaystJK client setup, remove the fs_game japlus argument and either remove the fs_forcegame argument or set it back to taystjk.

When to use vm_legacy

You should not need it. For each native module, TaystJK looks for the newer OpenJK-style GetModuleAPI entry point and, when the library does not export one, loads it through the older dllEntry/vmMain interface instead (sys_main.cpp, cl_uiapi.cpp). Older mods such as JA+ load this way with no setting. UI libraries built for other OpenJK-based clients load through GetModuleAPI: the engine only asks a UI library for cvar help when the library says it provides it, and otherwise uses its own descriptions (cl_uiapi.cpp).

vm_legacy forces the older interface for selected module slots, on a library that exports both. That matters in one case: the library’s GetModuleAPI rejects the engine’s API version, and the client stops with GetGameAPI failed on followed by the library name (cl_uiapi.cpp). It still loads a native library; it does not enable QVM support.

vm_legacy is a bitmask:

Add values to force more than one module, so 6 forces both cgame and UI. Put it on the command line, for example +set vm_legacy 4 for the UI library: it is read when a module loads, and changing it afterwards does not convert a module that is already running.

If the console then reports VM_CreateLegacy: ... succeeded, the older interface loaded. If it reports failed, the library has no older interface; remove the setting and check that the mod build matches your platform.

Steam playtime and overlay

Optional, and Windows only. Sys_SteamInit is an empty stub everywhere else (sys_unix.cpp).

With it working, Steam counts your TaystJK time against Jedi Academy and the overlay works, without having to launch the client through Steam.

com_steamIntegration is already on by default (common.cpp), so there is nothing to enable. It does nothing until you supply two files, neither of which ships with TaystJK or with retail Jedi Academy. Put both in GameData, beside the executable:

6020 is Jedi Academy’s Steam app ID.

Mind the architecture. The Steam Integration Tools package on JKHub is the usual source for these, but it provides the 32-bit steam_api.dll only. If you run the 64-bit build, as most people do, that package alone will not work; you need steam_api64.dll, which comes from the Steamworks SDK.

If the file is missing the client says so at startup in red, and otherwise runs normally:

Steam integration failed: Couldn't find steam_api64.dll

The cvar is latched, so a change needs a restart. Set com_steamIntegration 0 to stop the client looking at all.

Why you have to supply these: the Steamworks SDK’s terms do not fit TaystJK’s GPLv2 licence, so the library cannot be bundled. The client loads it at runtime if it finds it, which keeps the licences apart (sys_win32.cpp).

First-launch checks

• Open the console with Shift + ~ and run version to confirm that TaystJK is running.
• If the console reports that it cannot find default.cfg, TaystJK cannot see base/assets0.pk3. Recheck the extraction directory or fs_cdPath.
• If the client cannot load a renderer or library, re-extract the complete release, confirm its architecture, and revisit the platform prerequisites above.
• If settings or downloaded PK3s appear in an unexpected place, run path in the console and inspect fs_homepath, fs_basepath, and fs_game.

This layout is adapted from the longer multiple modded clients guide on JKHub.

Next steps

• What this client adds: the HUD tools, movement styles and cosmetics
• Something is wrong: listed by symptom, including the macOS and modded-server cases above
• Host a dedicated server
• Search cvars and commands
• Compile TaystJK from source

Last changed 28 September 2026 History Edit this page on GitHub