DOCSEARCHbyAlgolia
Submit Docs

PrimeXT Documentation

repository·master·Indexed 41 days ago

https://github.com/snmetamorph/primext

A modernized toolkit and HLSDK for the Xash3D FWGS engine designed for creating singleplayer and multiplayer mods. PrimeXT provides enhanced graphics including dynamic lighting with shadows, HDR rendering, and PhysX rigid body physics, while maintaining compatibility with GoldSrc content. The documentation covers installation, modding workflows, material systems, and API references for sprite drawing, sound playback, and server communication.

Tokens
62K
Snippets
90
Records
372
Agent score
41%

What's inside PrimeXT

  1. Overview of PrimeXT toolkit

    master

    PrimeXT is a modernized toolkit for the Xash3D FWGS engine. It is designed for creating both singleplayer and multiplayer mods, supporting cross-platform deployment. It inherits all functionality from XashXT and Spirit Of Half-Life while providing improved graphics, physics, and expanded engine limits.

    Key capabilities include:

    • Compatibility: Supports most content originally made for GoldSrc.
    • Graphics: Features dynamic lighting with shadows, normal/parallax mapping, cubemap reflections, HDR rendering with automatic exposure, 3D skyboxes, and post-processing effects (Bloom, Color Correction, Depth-of-field, Sun beams).
    • Physics: Includes rigid body physics via the PhysX engine.
    • Models: Supports inverse kinematics, jiggle bones, vertex weighting (up to 4 bones per vertex), and decals on studiomodels.
    • Engine Limits: Significantly extended map size limits (up to 65535x65535x65535 units) and expanded studiomodel limits.

  2. Overview of PrimeXT SDK

    master

    PrimeXT is a modernized SDK for the Xash3D FWGS engine, designed for compatibility with multiple modern platforms. It features improved graphics and physics while maintaining full compatibility with GoldSrc and Xash3D workflows and content. It is based on XashXT and inherits all functionality from XashXT and Spirit Of Half-Life, making it suitable for both single-player and multiplayer mods.

    Key Capabilities

    Engine & Content Compatibility

    • High compatibility with GoldSrc engine content.
    • Removal of many limits inherent to GoldSrc and vanilla Xash3D.
    • Significantly expanded map size limits (up to 65535x65535x65535 units).
    • Expanded limits for studio models (reducing the need to split into many SMD files).

    Graphics & Rendering

    • Optimized studio model rendering with support for Inverse Kinematics (IK), jiggle bones, and vertex weighting (up to 4 bones per vertex).
    • Support for decals on studio models.
    • Dynamic lighting with shadowing.
    • Normal mapping and Parallax mapping.
    • Parallax-corrected cubemap reflections.
    • HDR rendering with automatic exposure correction (eye adaptation).
    • 3D skyboxes.
    • Post-processing effects: Color correction, Bloom, Depth of Field (DoF), and Sunshafts/Godrays.
    • Mirrors and monitors capable of displaying camera views.
    • Portals that allow entities to move through them.

    Physics & UI

    • Rigid body physics powered by the PhysX engine.
    • Built-in ImGui support for in-game or debugging user interfaces.

    Development Tools

    • A custom suite of development utilities, including model and map compilers, and model/sprite viewers.

  3. Overview of the pxstudiomdl model compiler

    master

    The pxstudiomdl is a model compiler derived from the Paranoia 2 Savior studiomdl. It is designed for use with Xash3D and PrimeXT, though it maintains compatibility with GoldSrc. It features expanded limits for vertices in models and SMD files, and includes several modern features for texture and animation handling.

    Key Features:

    • Texture Support: Supports full-color textures in TGA, BMP, PNG, and DDS formats. It automatically generates transparency for embedded textures if the input textures contain an alpha channel.
    • Tiling: Supports texture tiling on models (exclusive to PrimeXT/Xash3D) and fake texture tiling for GoldSrc (up to four repetitions).
    • Animation & Rigging: Supports bone weighting and procedural bone animation (jiggle bones).
    • Robustness: Automatically replaces missing textures with a placeholder texture.
    • Simplified Workflow: Allows direct compilation of SMD files without manually creating a QC file, provided the model contains no animations.

  4. Understand the basics of Half-Life 1 modding

    master

    Modding Half-Life 1 (GoldSrc/Xash3D engines) can be categorized into two main approaches:

    1. Basic Modding (Content Replacement)

    This involves replacing or adding assets like sounds, models, or textures. You can achieve this by finding the target file in the game folder and replacing it with your own.

    • Resources: You can find community assets on sites like ModDB, GameBanana, or Gamer-Lab.
    • Map Editing: To modify existing maps, you can use bspguy. To create maps from scratch, you will need a dedicated map editor and a compilation process.

    2. Advanced Modding (Code-based)

    For projects that require new gameplay mechanics or logic beyond simple asset swaps, you must use the Half-Life SDK (HLSDK). The SDK is a collection of C++ source code for utilities, the client library, and the server library. Using the SDK allows you to implement custom features by modifying the underlying engine logic.

  5. Use trigger_sound to change DSP effects based on area

    master

    The trigger_sound entity acts as a replacement for env_sound. It allows you to define a zone that triggers a change in DSP (Digital Signal Processing) effects precisely according to the trigger's area.

    Key behaviors:

    • It can change DSP settings for exactly one effect.
    • To reset a DSP effect to zero, you must use an additional object.
    • The trigger cannot be activated via targetname; it can only be activated by player contact (touching the trigger area).

  7. Implement the parent system with env_model

    master

    When using the parent system (attaching an env_model to another entity via the Parent key), follow these requirements:

    1. Precise Placement: To ensure correct engine interpretation, the model must be placed very accurately in the map editor. For example, if attaching a door model to a func_door_rotating, place the model directly inside the target entity to prevent following errors during movement.
    2. Collision Conflict: Be aware that collision (Solid flag) interacts poorly with the parent system. If collision is enabled while the model is following another object, the physical collision shell may remain at the original location instead of moving with the model.

  9. Use Gloss/PBR textures for surface properties

    master

    Gloss/PBR textures define surface properties like smoothness and metalness. You can identify these textures using the suffixes _gloss or _pbr. The way these textures are interpreted depends on the lighting algorithm selected via the r_lighting_brdf setting.

    Example: If your base texture is wall1.dds, the gloss/PBR texture should be named wall1_gloss.dds or wall1_pbr.dds.

    Classic Lighting (r_lighting_brdf 0)

    In this mode, the texture controls surface smoothness and specular highlight intensity using only the Red channel:

    • Red Channel: Intensity of specular highlights (0 = no highlights, 1 = maximum brightness).
    • Other channels are ignored.

    Physically Correct (PBR) Lighting (r_lighting_brdf 1)

    In PBR mode, the texture stores multiple parameters across its RGBA channels.

    Warning: The PBR pipeline is currently under development. Changes to the implementation may occur, which could affect existing content. For stability, it is recommended to use the Classic algorithm for critical content.

    ChannelParameterDescription
    RSmoothnessSurface smoothness (0 = very rough, 1 = perfectly smooth). This is the inverse of roughness.
    GMetalnessMetal level (0 = dielectric, 1 = pure metal). Intermediate values may cause light rim artifacts.
    BAmbient occlusionSelf-shadowing (0 = fully shadowed, 1 = no shadowing). Helps emphasize small crevices.
    ASpecular intensityBrightness of specular reflections (0 = none, 1 = 100% original brightness). It is highly recommended to keep this at 1 if not manually adjusting for artistic control.

  10. Configure physics behavior for env_shooter gibs

    master

    The Behaviour of children parameter determines how the ejected pieces interact with the environment. Choose a mode based on the desired movement pattern:

    • 0 (Normal): Standard gib physics.
    • 1 (Stick to wall): Pieces stick to walls (including moving objects) after the first contact.
    • 2 (NOCLIP): Pieces do not collide with anything.
    • 3 (FLYMISSILE): Ignores gravity; uses a special hull for collision detection.
    • 4 (BOUNCEMISSILE): Bounces off walls and ignores gravity; uses a special hull for collision detection.
    • 5 (TOSS): Does not use extra-bounce; pieces simply slide along the floor while being affected by gravity.
    • 6 (PHYSIC): Uses the full physics engine for simulation.

  11. Use the env_static_decal entity for HD decals

    master

    The env_static_decal is a point entity used to place HD decals on a location. These decals are sourced from the gfx\decals folder and serve as a modern alternative to the legacy decals used in Half-Life 1.

    To use this entity, you must define a decal group name that corresponds to an entry in the decalinfo.txt file located within the gfx\decals directory.

    grafity1 
{
	grafity2 48 48 1
}

  12. Configure NPC behavior using the Behave as parameter

    master

    In PrimeXT, NPC behavior is decoupled from the entity's specific class. This allows you to customize the temperament of any monster (e.g., making a specific soldier friendly or hostile) without changing its base entity type.

    To change how an entity acts, use the Behave as parameter. This parameter is available on all entities that have the monster_ prefix.