Pragma Engine

Introduction

pragma_logo_256.pngWhat is Pragma?

youtube_social_square_red32.png Discord-Logo-Color.png

Pragma is a free, open source custom game engine written in C++. Here is an overview over some of its core features:

Pragma is currently in an early beta, some features may not be fully functional at the moment or are unfinished/experimental.

 

Pragma also ships with the Pragma Filmmaker, an open source alternative to the Source Filmmaker.

You can use the Book Navigation on the left to navigate to the next page, which has details on how to download and install Pragma.

Click the firefox_2020-08-12_15-57-16.png button at the top right for other topics (such as the API documentation for developers).

 

Media

Download

System requirements

 

Download

Standalone

download.png

Download the "-win64.zip" version if you're on a Windows OS, and "-lin64.tar.gz" for Linux.
No installation is required, simply extract the archive somewhere and run the "pfm.exe".

 

Source Code

Pragma and PFM are both completely open-source on GitHub, which means you can also build them yourself. For more information, check out this article.

Changelog

See progress reports for a showcase of new features.

Version 1.0.5 [2022-08-30]

Filmmaker v0.4.6
Engine
Lua

 

Version 1.0.4 [2022-05-31]

Filmmaker v0.4.5
Engine
Lua

 

Version 1.0.2 [2021-09-13]

Filmmaker v0.4.3

LuxCoreRender

 

Engine

 

Lua

 

Version 1.0.1 [2021-06-22]

Filmmaker v0.4.2

 

Engine

 

Lua

 

Version 0.9.15 [2021-05-30]

Filmmaker v0.4.1

 

Engine

 

Lua

 

Version 0.9.14 [21-04-16]

Filmmaker
Engine
Lua

 

Version 0.9.13 [2021-03-14]

Filmmaker
Engine
Lua

 

Version 0.9.12 [2021-02-08]

Filmmaker
Engine
Lua

 

Version 0.9.11 [2020-11-11]

Filmmaker
Engine
Lua

 

Version 0.9.10

Filmmaker
Engine
Lua

 

Troubleshooting

Pragma crashes on startup

If Pragma crashes on startup, please ensure that your system fulfills the system requirements and that your graphics drivers are up to date.

If you have multiple GPUs, please make sure to enable your high-default GPU as the default for Pragma. You can follow the instructions on this page to do so.

 

There is no text in the main menu

Try adding -graphics_api vulkan to the launch options in Pragma to switch to the Vulkan renderer:

firefox_2020-08-21_09-35-29.png

 

I have an AMD GPU and Pragma/PFM crashes on startup

This should be fixed in newer versions of PFM, until they are released publicly, you can try this temporary fix:

  1. Go to the Pragma root folder
  2. Remove the `cache` directory
  3. Go to `Pragma/shaders/world/eye/`
  4. Rename `fs_eye.gls` to `fs_eye_bak.gls`
  5. Launch PFM

Character eyes won't be rendered properly in the real-time render viewport, but it shouldn't be freezing anymore.

Mapping

Asset Import / Export

Export

Pragma comes with the following export capabilities:

Exporting Assets

If you want to export a model or material, the easiest way to do so is via the Filmmaker interface. Simply open the model/material catalog, right click on the model icon, then click "Export asset":

export_model_asset.png

If you want to export a different asset type, or need more control, you can use the export command utility instead. To use it, start a game in Pragma first. You can either load a map (which map doesn't matter), or run "map empty" in the console. Once the map has been loaded, you can use the "util_export_asset" console command with the following parameters:

Models only:

If you want to use Pragma to export Source Engine assets, you generally don't have to copy any of the assets to Pragma, the Engine should be able to locate the assets automatically as long as they're part of one of your installed Source Engine games on Steam.

 

Usage Examples

Exporting a material (including textures):

util_export_asset -material "brick/brick_1a" -verbose -image_format png

Exporting a texture:

util_export_asset -texture "concrete/concrete_5_floor_3_psd_918fcd2d" -verbose -image_format png

Exporting a map:

util_export_asset -map "gm_construct" -verbose -export_images 1 -image_format png -generate_ao 0 -export_animations 0

Exporting a model:

util_export_asset -model "props_2fort/tank001" -verbose -image_format png -generate_ao 0

(Make sure to remove the ".mdl" extension!)

Exporting a Source 2 model:

util_export_asset -model "characters/gman/gman" -verbose -image_format png -generate_ao 0

Batch-exporting all models in a directory and all sub-directories:

util_export_asset -model "props_2fort" -verbose -image_format png -generate_ao 0 -recursive 1

 

Exporting retargeted models

This section refers to PFM v0.4.3 and newer and may not be representative of older versions.

It is also possible to export a model with retargeted animations (i.e. export a model with the animations of another model.):

2021-09-24_21-16-05.gif

To do so, you will have to set up a retarget rig in PFM's retarget editor first:

Once you have created the retarget rig, you can use the -retarget_source argument in the util_export_asset command to export the model with the retargeted animations:

util_export_asset -model "e3assassin" -retarget_source "re5/jv1" -verbose -image_format tga -generate_ao 0 -embed_animations 1

 

Exporting to Source Engine

You can also use the command to export a model to the Source Engine .mdl format. To do so, simply set the "format" parameter to "mdl":

util_export_asset -model "props_2fort/tank001" -format "mdl"

Most of the parameters listed above will have no effect when using the Source Engine mdl-exporter!

This will automatically generate the QC and SMD files for the model, convert the textures to vtf, convert the materials to vmt, as well as automatically compile the model using studiomdl. Pragma will attempt to locate studiomdl automatically, but you can also specify which game's studiomdl should be used:

util_export_asset -model "props_2fort/tank001" -format "mdl" -game "tf2"

This will use the studiomdl from TF2. The game name has to match the entry from "Pragma/cfg/mounted_games.udm" (You can open the file in a text-editor).

If the model's materials use PBR, the exporter will also automatically apply fake PBR for use in SFM.

All of the model's animations will be included in the Source Engine model as well, however morph targets are currently not supported.

Using Pragma to convert models from Blender to Source

Converting a model from Blender (or other modelling programs) is very simple. All you have to do is export your model from Blender in either the glTF format, or the glb format and copy the exported file to "Pragma/addons/imported/models". Then use the command above and replace the model name with the name of the glTF/glb file (without the extension).

 

Source 2

The approach for Source 2 assets is exactly the same as for Source 1 assets, with the exception of maps. To export a Source 2 map, follow these steps (using Half-Life: Alyx as an example):

  1. Open the map's vpk-file (steamapps/common/Half-Life Alyx/game/hlvr/maps) in GCFScape
  2. Extract all of the files from the vpk to "Pragma/addons/imported/"
  3. Run the "util_export_asset" command with the asset name pointing to the "vwrld_c"-file. For example, for the map "a5_vault", you should use:
util_export_asset -map "a5_vault/world" -verbose -export_images 1 -image_format png -generate_ao 0

 

Import

If you want to import a model from Blender (or other modelling programs), all you have to do is export the model in the glTF or glb format and copy the exported file to "Pragma/addons/imported/models". The model should automatically show up in the PFM model catalog and it will automatically get converted (along with the textures) when used.

Source Engine / Source 2

If you want to import a model (or material/texture) from Source or Source 2, you generally don't have to do anything. All of your installed Source Engine games (assuming they're installed via Steam) should be automatically detected and mounted by Pragma. In the rare event that this doesn't work, you can try adding the mount path for the game to "Pragma/cfg/mounted_games.udm".

Alternatively you can also simply extract the asset files to "Pragma/addons/imported/models" and "Pragma/addons/imported/materials" respectively.

Console Commands

Variables

audio_api <audioApi>

Type: String

The underlying audio API to use.

cache_version <value>

Type: String

The engine version that the cache files are associated with. If this version doesn't match the current engine version, the cache will be cleared.

cache_version_target <value>

Type: String

If cache_version does not match this value, the cache files will be cleared and it will be set to it.

cl_allowdownload <value>

Type: String

 

cl_allowupload <value>

Type: String

 

cl_audio_always_play <value>

Type: String

0 = Don't play sounds if window isn't focused., 1 = Always play sounds

cl_audio_hrtf_enabled <value>

Type: String

Enables or disables Head-related transfer function.

cl_audio_master_volume <value>

Type: String

Volume scale for all sounds.

cl_audio_streaming_enabled <value>

Type: String

0 = All sounds will be loaded immediately (= Slower load times), 1 = Some sounds will be loaded over time. (= Sounds might start with a delay)

cl_controller_axis_input_threshold <value>

Type: String

Axis inputs below this threshold will be ignored for regular console commands.

cl_controller_enabled <value>

Type: String

Enables or disables game controllers / joysticks.

cl_downscale_imported_high_resolution_rma_textures 1/0

Type: Boolean

If enabled, imported high-resolution RMA textures will be downscaled to a more memory-friendly size.

cl_effects_volume <value>

Type: String

Volume scale for effect sounds (e.g. footsteps, gunshots, explosions, etc.).

cl_flex_phoneme_drag <value>

Type: String

Changes the time required for facial phoneme flexes to adapt to new phonemes.

cl_fov <value>

Type: String

Horizontal world field of view.

cl_fov_viewmodel <value>

Type: String

Horizontal view model field of view.

cl_fps_decay_factor <value>

Type: String

How slowly to decay the previous fps.

cl_gpu_device <value>

Type: String

The unique identifier for the GPU vendor and device to use. If empty (or invalid), the first detected device will be used. Usage: <vendorId,deviceId>

cl_gpu_timer_queries_enabled <value>

Type: String

Enables or disables GPU timer queries for debugging.

cl_gui_volume <value>

Type: String

Volume scale for sounds emitted by GUI elements.

cl_language <value>

Type: String

Game language.

cl_material_streaming_enabled <value>

Type: String

0 = All materials and textures will be loaded immediately (= Slower load times), 1 = All materials and textures will be loaded over time. (= Black textures until loaded)

cl_max_fps <value>

Type: String

FPS will be clamped at this value. A value of < 0 deactivates the limit.

cl_mouse_acceleration <value>

Type: String

Amount of mouse acceleration. 1 = No acceleration.

cl_mouse_pitch <value>

Type: String

Mouse sensitivity on the pitch axis. Use positive values to invert the axis.

cl_mouse_sensitivity <value>

Type: String

Scale for the mouse sensitivity.

cl_mouse_yaw <value>

Type: String

Mouse sensitivity on the yaw axis.

cl_music_volume <value>

Type: String

Volume scale for music.

cl_physics_simulation_enabled <value>

Type: String

Enables or disables physics simulation.

cl_port_tcp <value>

Type: String

Port used for TCP transmissions.

cl_port_udp <value>

Type: String

Port used for UDP transmissions.

cl_render_anti_aliasing <value>

Type: String

0 = No Anti Aliasing, 1 = MSAA, 2 = FXAA.

cl_render_brightness <value>

Type: String

Scene brightness.

cl_render_contrast <value>

Type: String

Scene contrast.

cl_render_depth_of_field <value>

Type: String

Depth of field scale.

cl_render_fov <value>

Type: String

Specifies the horizontal field of view.

cl_render_frustum_culling_enabled <value>

Type: String

Enables or disables frustum culling.

cl_render_fxaa_edge_threshold <value>

Type: String

The minimum amount of local contrast required to apply algorithm.

cl_render_fxaa_min_edge_threshold <value>

Type: String

Trims the algorithm from processing darks.

cl_render_fxaa_sub_pixel_aliasing_removal_amount <value>

Type: String

The amount of sub-pixel aliasing removal.

cl_render_lod_bias <value>

Type: String

Model LOD-bias. Higher values means higher LOD-Models will be used at lower distance (=Lower quality).

cl_render_monitor <value>

Type: String

Which monitor to use in fullscreen mode.

cl_render_motion_blur <value>

Type: String

Amount of motion blur. 0 = disabled.

cl_render_msaa_samples <value>

Type: String

1 = MSAAx2, 2 = MSAAx4, 3 = MSAAx8, etc.

cl_render_occlusion_culling <value>

Type: String

0 = Off, 1 = Brute-Force, 2 = CHC++, 3 = Octree, 4 = BSP +Octree

cl_render_particle_quality <value>

Type: String

Quality of particle systems. 0 = No particles will be rendered, 1 = Particles will be unlit, 2 = Particles will receive lighting, 3 = Particles will cast shadows.

cl_render_present_mode <value>

Type: String

0 = Immediate, 1 = FIFO, 2 = Mailbox

cl_render_preset <value>

Type: String

Selected preset in display options.

cl_render_reflection_quality <value>

Type: String

Changes the quality of reflections. 0 = Only static reflections, 1 = Dynamic reflections, 2 = Reflections with particle effects.

cl_render_resolution <value>

Type: String

Changes the internal rendering resolution. If left empty, the resolution will be the same as the window resolution!

cl_render_shader_quality <value>

Type: String

Shader quality. The actual effect depends on the shader. 1 = Lowest Quality, 10 = Highest Quality

cl_render_shadow_dynamic <value>

Type: String

Turns dynamic shadows on or off.

cl_render_shadow_lod_bias <value>

Type: String

Model LOD-bias for shadows. Higher values means higher LOD-Models will be used at lower distance (=Lower quality). This value is added on top of cl_render_lod_bias!

cl_render_shadow_pssm_split_count <value>

Type: String

The number of cascades to be used for PSSM. Cannot be 0 or higher than 4.

cl_render_shadow_pssm_update_frequency_offset <value>

Type: String

Update frequency for PSSM shadows in frames, relative to 'cl_render_shadow_update_frequency'.

cl_render_shadow_resolution <value>

Type: String

Shadowmap Resolution. Higher resolution equals higher quality shadows, but is also more expensive to render.

cl_render_shadow_update_frequency <value>

Type: String

Update frequency in frames. 0 = Updates every frame, 1 = Updates every second frame, etc.

cl_render_ssao <value>

Type: String

1 = Screen space ambient occlusion enabled, 0 = disabled.

cl_render_texture_filtering <value>

Type: String

0 = Nearest Neighbour, 1 = Bilinear Filtering, 2 = Trilinear Filtering, 3 = Antisotropic Filtering x2, 4 = Antisotropic Filtering x4, 5 = Antisotropic Filtering x8, 6 = Antisotropic Filtering x16

cl_render_texture_quality <value>

Type: String

0 = Minimal, 1 = Low, 2 = Medium, 3 = High, 4 = Very High.

cl_render_tone_mapping <value>

Type: String

Changes the tone-mapping algorithm to use. -1 = Use the default, 0 = Gamma correction only, 1 = Reinhard, 2 = Hejil-Richard, 3 = Uncharted, 4 = Aces, 5 = Gran Turismo

cl_render_vr_enabled <value>

Type: String

Turns support for virtual reality on or off.

cl_render_vsync_enabled <value>

Type: String

Turns vertical sync on or off.

cl_render_window_mode <value>

Type: String

0 = Fullscreen, 1 = Windowed, 2 = Windowed no-border.

cl_show_fps <value>

Type: String

Displays the current fps at the top left of the screen if enabled.

cl_steam_audio_ambisonics_order <value>

Type: String

The amount of directional detail in the simulation results. Range: [0,3].

cl_steam_audio_enabled <value>

Type: String

Enables or disables steam audio.

cl_steam_audio_ir_duration <value>

Type: String

The time delay between a sound being emitted and the last audible reflection. Range: [0.5,4.0].

cl_steam_audio_number_of_bounces <value>

Type: String

The maximum number of times any ray can bounce within the scene. Range: [1,32].

cl_steam_audio_number_of_diffuse_samples <value>

Type: String

The number of directions to consider when a ray bounces off a diffuse (or partly diffuse) surface. Range: [32,4096].

cl_steam_audio_number_of_rays <value>

Type: String

The number of rays to trace from the listener. Range: [1024,131072].

cl_steam_audio_propagation_delay_enabled <value>

Type: String

Enables or disables propagation delay if steam audio is enabled.

cl_steam_audio_reverb_enabled <value>

Type: String

Enables the reverb DSP effect.

cl_steam_audio_reverb_indirect_binaural <value>

Type: String

Spatialize reverb using HRTF.

cl_steam_audio_reverb_simulation_type <value>

Type: String

Real-time or baked. 0 = Real-time, 1 = Baked.

cl_steam_audio_spatialize_air_absorption <value>

Type: String

Enable air absorption.

cl_steam_audio_spatialize_direct_binaural <value>

Type: String

Spatialize direct sound using HRTF.

cl_steam_audio_spatialize_direct_level <value>

Type: String

Relative level of direct sound. Range: [0,1].

cl_steam_audio_spatialize_distance_attenuation <value>

Type: String

Enable distance attenuation. If disabled, regular distance attenuation will be used instead.

cl_steam_audio_spatialize_enabled <value>

Type: String

Enables the spatialize DSP effect.

cl_steam_audio_spatialize_hrtf_interpolation <value>

Type: String

HRTF interpolation. 0 = Nearest, 1 = Bilinear.

cl_steam_audio_spatialize_indirect <value>

Type: String

Enable indirect sound.

cl_steam_audio_spatialize_indirect_binaural <value>

Type: String

Spatialize indirect sound using HRTF.

cl_steam_audio_spatialize_indirect_level <value>

Type: String

Relative level of indirect sound. Range: [0,10].

cl_steam_audio_spatialize_occlusion_method <value>

Type: String

Direct occlusion algorithm. 0 = Raycast, 1 = Partial.

cl_steam_audio_spatialize_occlusion_mode <value>

Type: String

Direct occlusion and transmission mode. 0 = Off, 1 = On, No Transmission, 2 = On, Frequency Independent Transmission, 3 = On, Frequency Dependent Transmission.

cl_steam_audio_spatialize_simulation_type <value>

Type: String

Real-time or baked. 0 = Real-time, 1 = Baked

cl_steam_audio_spatialize_static_listener <value>

Type: String

Uses static listener.

cl_updaterate <value>

Type: String

The amount of times per second user input is being transmitted to the server.

cl_voice_volume <value>

Type: String

Volume scale for voice (Coming from players and NPCs).

cl_vr_hmd_view_enabled <value>

Type: String

Enables or disables the view for virtual reality (Only works if virtual reality has been enabled in the menu.).

cl_vr_mirror_window_enabled <value>

Type: String

Enables or disables the mirror window for virtual reality (Only works if virtual reality has been enabled in the menu.).

cl_water_surface_simulation_edge_iteration_count <value>

Type: String

The more iterations, the more detailed the water simulation will be, but at a great performance cost.

cl_water_surface_simulation_enable_gpu_acceleration <value>

Type: String

If enabled, water surfaces will be simulated on the GPU instead of the CPU. This should greatly improve performance in most cases.

cl_water_surface_simulation_spacing <value>

Type: String

Grid spacing for simulating water surfaces. Lower values will result in a more detailed simulation, but at a great performance cost.

cl_window_resolution <value>

Type: String

Changes the window resolution.

debug_ai_navigation <value>

Type: String

Displays the current navigation path for all NPCs.

debug_bsp_lock <value>

Type: String

Locks BSP culling so it doesn't change when the camera moves.

debug_bsp_nodes <value>

Type: String

Prints and draws various debug information about the binary space partitioning of the level (if available). 1 = Draw leaf of camera location and all visible leaves, 2 = Same, but doesn't update continuously.

debug_hide_gui 1/0

Type: Boolean

Disables GUI rendering.

debug_nav_show_meshes <value>

Type: String

Shows the navigation mesh for this map.

debug_occlusion_culling_freeze_camera <value>

Type: String

Freezes the current camera position in place for occlusion culling.

debug_particle_blob_show_neighbor_links <value>

Type: String

debug_physics_draw <value>

Type: String

Draws various physics information as wireframe.

debug_profiling_enabled <value>

Type: String

Enables profiling timers.

debug_render_lock_render_command_buffers <value>

Type: String

Locks the current render command buffers and causes them to not be re-created every frame.

debug_render_lock_render_queues <value>

Type: String

Locks the current render queues and effectively disables the render queue thread.

debug_render_normals <value>

Type: String

Displays all normals as lines in the world. 0 = Disabled, 1 = Display normals, 2 = Display normals, tangents and bitangents, 3 = Display face normals, 4 = Display tangents, 5 = Display bitangents.

debug_render_octree_dynamic_draw <value>

Type: String

Draws the octree for dynamic objects.

debug_render_octree_static_draw <value>

Type: String

Draws the octree for static world geometry.

debug_steam_audio_probe_boxes <value>

Type: String

Displays the sound probe spheres for the current map.

host_timescale <value>

Type: String

Specifies the timescale. A value of 2 means the game will run at twice the default speed.

log_enabled <value>

Type: String

0 = Log disabled; 1 = Log errors only; 2 = Log errors and warnings; 3 = Log all console output

log_file <value>

Type: String

The log-file the console output will be logged to.

lua_open_editor_on_error <value>

Type: String

1 = Whenever there's a Lua error, the engine will attempt to automatically open a Lua IDE and open the file and line which caused the error.

net_graph <value>

Type: String

Displays a graph about current network transmissions.

net_library <netLibrary>

Type: String

The underlying networking library to use for multiplayer games.

password <value>

Type: String

Password which will be used for the next connection attempt.

phys_engine <physEngie>

Type: String

The underlying physics engine to use.

playername <value>

Type: String

Local player name.

rcon_password <value>

Type: String

Specifies a password which can be used to run console commands remotely on a server. If no password is specified, this feature is disabled.

render_api <renderApi>

Type: String

The underlying rendering API to use.

render_bloom_amount <value>

Type: String

Number of render passes to use for bloom.

render_bloom_enabled <value>

Type: String

Enables or disables bloom and glow effects.

render_bloom_resolution <value>

Type: String

The width for the bloom texture. The height will be calculated using the aspect ratio of the renderer.

render_clear_scene <value>

Type: String

0 = Default, 1 = Screen is cleared before scene is rendered.

render_clear_scene_color <value>

Type: String

Clear color to use if render_clear_scene is set to 1.

render_csm_max_distance <value>

Type: String

The maximum distance at which csm shadows are casted. A larger distance means lower quality.

render_debug_mode 1/0

Type: Boolean

0 = Disabled, 1 = Ambient Occlusion, 2 = Albedo Colors, 3 = Metalness, 4 = Roughness, 5 = Diffuse Lighting, 6 = Normals, 7 = Normal Map, 8 = Reflectance, 9 = IBL Prefilter, 10 = IBL Irradiance, 11 = Emission, 12 = Lightmaps, 13 = Lightmap Uvs, 14 = Unlit, 15 = Show CSM cascades, 16 = Shadow Map Depth, 17 = Forward+ Heatmap.

render_draw_dynamic <value>

Type: String

1 = Default, 0 = Don't draw props.

render_draw_glow <value>

Type: String

1 = Default, 0 = Glow-effects aren't drawn.

render_draw_particles <value>

Type: String

1 = Default, 0 = Particles aren't drawn.

render_draw_scene <value>

Type: String

1 = Default, 0 = Scene isn't drawn.

render_draw_sky <value>

Type: String

1 = Default, 0 = Sky isn't drawn.

render_draw_static <value>

Type: String

1 = Default, 0 = Don't draw level geometry.

render_draw_translucent <value>

Type: String

1 = Default, 0 = Don't draw translucent objects.

render_draw_view <value>

Type: String

1 = Default, 0 = View-Models aren't drawn.

render_draw_water <value>

Type: String

1 = Default, 0 = Water isn't drawn.

render_draw_world <value>

Type: String

1 = Default, 2 = Wireframe, 0 = Don't draw world.

render_dynamic_lighting_enabled 1/0

Type: Boolean

Enables or disables dynamic lighting.

render_dynamic_shadows_enabled 1/0

Type: Boolean

Enables or disables dynamic shadows.

render_forwardplus_tile_size <value>

Type: String

Changes the tile size used for the light culling in forward+.

render_hdr_max_exposure <value>

Type: String

Expore will be clamped at this value. Can be overwritten by the map.

render_ibl_enabled 1/0

Type: Boolean

Enables or disables image-based lighting.

render_instancing_enabled 1/0

Type: Boolean

Enables or disables instanced rendering.

render_instancing_threshold [2,inf]

Type: UInt32

The threshold at which to start instancing entities if instanced rendering is enabled (render_instancing_threshold). Must not be lower than 2!

render_multithreaded_rendering_enabled 1/0

Type: Boolean

Enables or disables multi-threaded rendering. Some renderers (like OpenGL) don't support multi-threaded rendering and will ignore this flag.

render_normalmapping_enabled <value>

Type: String

1 = Normal mapping enabled, 0 = disabled.

render_pp_nightvision <value>

Type: String

Enables or disables night vision.

render_pp_nightvision_color_amplification <value>

Type: String

Amplification factor for pixels with low luminance.

render_pp_nightvision_luminance_threshold <value>

Type: String

Changes the luminance threshold for the night vision post-processing effect.

render_pp_nightvision_noise_texture <value>

Type: String

Noise texture to use for the night vision post-processing effect.

render_queue_entities_per_worker_job [1,50]

Type: UInt32

Number of entities for each job processed by a worker thread.

render_queue_worker_jobs_per_batch [0,10]

Type: UInt32

Number of worker jobs to accumulate in a batch before assigning a worker.

render_queue_worker_thread_count [1,10]

Type: UInt32

Number of threads to use for generating render queues.

render_shadow_quality <value>

Type: String

Shadowmap Quality. This affects the detail of the object shadows that are being rendered

render_technique <value>

Type: String

0 = Rasterization, 1 = Raytracing

render_texture_filtering <value>

Type: String

0 = Nearest-Neighbor, 1 = Bilinear, 2 = trilinear.

render_vsync_enabled <value>

Type: String

1 = Vertical sync enabled, 0 = disabled.

sh_lua_remote_debugging <value>

Type: String

0 = Remote debugging is disabled; 1 = Remote debugging is enabled serverside; 2 = Remote debugging is enabled clientside. Cannot be changed during an active game. Also requires the "-luaext" launch parameter. Remote debugging cannot be enabled clientside and serverside at the same time.

sh_mount_external_game_resources <value>

Type: String

If set to 1, the game will attempt to load missing resources from external games.

sky_override <value>

Type: String

Replaces the material for all current skyboxes with the specified material.

steam_steamworks_enabled <value>

Type: String

Enables or disables steamworks.

sv_acceleration <value>

Type: String

Player acceleration. If this is too low, the player will be unable to reach full movement speed due to friction forces.

sv_allowcslua <value>

Type: String

1 = Clients can run own clientside scripts, 0 = Custom clientside scripts aren't allowed.

sv_allowdownload <value>

Type: String

Specifies whether clients are allowed to download resources from the server.

sv_allowupload <value>

Type: String

Specifies whether clients are allowed to upload resources to the server (e.g. spraylogos).

sv_cheats <value>

Type: String

Allows clients to run console commands which are marked as cheats if set to 1.

sv_debug_physics_draw <value>

Type: String

Draws various serverside physics information as wireframe.

sv_friction <value>

Type: String

Global friction scale.

sv_gamemode <value>

Type: String

Gamemode which should be used when starting a game.

sv_gravity <value>

Type: String

Specifies the default gravity force and direction. Certain entities may overwrite this for themselves.

sv_maxplayers <value>

Type: String

Specifies the maximum amount of players that are allowed to join the server.

sv_noclip_speed <value>

Type: String

The speed at which players can move in noclip mode.

sv_password <value>

Type: String

Sets a password for the server. No player will be able to join, unless they provide the correct password using the 'password' command.

sv_physics_simulation_enabled <value>

Type: String

Enables or disables physics simulation.

sv_player_air_move_scale <value>

Type: String

The scale at which players are still able to move while in the air. 0 = Players can't move until they've landed, 1 = Players can move freely while in the air

sv_port_tcp <value>

Type: String

TCP port which will be used when starting a server.

sv_port_udp <value>

Type: String

UDP port which will be used when starting a server.

sv_require_authentication 1/0

Type: Boolean

If enabled, clients will have to authenticate via steam to join the server.

sv_restitution <value>

Type: String

Global restitution scale.

sv_servername <value>

Type: String

The server name which will be displayed in the server browser.

sv_tickrate <value>

Type: String

Specifies the tickrate. A higher tickrate means smoother and more reliable physics, but also more data to transmit to clients. Higher values can result in more lag for clients.

sv_timeout_duration <value>

Type: String

Amount of time until a client is forcibly dropped if no data has been received.

sv_use_p2p_if_available <value>

Type: String

Use a peer-to-peer connection if the selected networking layer supports it.

sv_water_surface_simulation_edge_iteration_count <value>

Type: String

The more iterations, the more detailed the water simulation will be, but at a great performance cost.

sv_water_surface_simulation_shared <value>

Type: String

If enabled, water surface simulation will be shared between client and server (Simulation is only performed once). This will only have an effect in single-player or on listen servers.

Commands

+attack

Triggers the primary fire for the player character's equipped weapon.

+attack2

Triggers the secondary fire for the player character's equipped weapon.

+attack3

Triggers the tertiary fire for the player character's equipped weapon.

+attack4

Triggers the quaternary fire for the player character's equipped weapon.

+backward

Moves the player character backward while active.

+crouch

Prompts the player character to crouch.

+forward

Moves the player character forward while active.

+jump

Prompts the player character to jump.

+left

Moves the player character left while active.

+reload

Triggers the reload for the player character's equipped weapon.

+right

Moves the player character right while active.

+sprint

Enables sprinting while moving forward.

+turn_down

Continuously turns the player character leftwards.

+turn_left

Continuously turns the player character leftwards.

+turn_right

Continuously turns the player character leftwards.

+turn_up

Continuously turns the player character leftwards.

+use

Prompts the player character to use whatever is in front of him.

+walk

Enables walking while moving forward.

-attack

Triggers the primary fire for the player character's equipped weapon.

-attack2

Triggers the secondary fire for the player character's equipped weapon.

-attack3

Triggers the tertiary fire for the player character's equipped weapon.

-attack4

Triggers the quaternary fire for the player character's equipped weapon.

-backward

Moves the player character backward while active.

-crouch

Prompts the player character to crouch.

-forward

Moves the player character forward while active.

-jump

Prompts the player character to jump.

-left

Moves the player character left while active.

-reload

Triggers the reload for the player character's equipped weapon.

-right

Moves the player character right while active.

-sprint

Enables sprinting while moving forward.

-turn_down

Continuously turns the player character leftwards.

-turn_left

Continuously turns the player character leftwards.

-turn_right

Continuously turns the player character leftwards.

-turn_up

Continuously turns the player character leftwards.

-use

Prompts the player character to use whatever is in front of him.

-walk

Enables walking while moving forward.

asset_clear_unused

Clears all unused assets from memory.

asset_clear_unused_materials

Clears all unused materials from memory.

asset_clear_unused_models

Clears all unused models from memory.

asset_clear_unused_textures

Clears all unused textures from memory.

bind

Binds a key to a command string. Usage: bind <key> <command>

bind_keys

Prints a list of all bindable keys to the console.

cl_debug_netmessages

Prints out debug information about recent net-messages.

cl_entities

Prints a list of all current clientside entities in the world.

cl_find

Finds similar console commands to whatever was given as argument.

cl_gpu_timer_queries_dump

Prints all timer query results to the console.

cl_list

Prints a list of all clientside console commands to the console.

cl_send

Sends a text message to the server and displays it in the console. Usage: cl_send <message>

cl_send_udp

Sends a text message to the server via UDP and displays it in the console. Usage: cl_send_udp <message>

cl_steam_audio_reload_scene

Reloads the steam audio scene cache.

clear

Clears everything in the console.

clear_cache

Clears all of the cached engine files.

closeserver

Closes the server (if active) and drops all connected clients.

connect

Attempts to connect to the specified server. Usage: connect <ipV6/ipV4> or connect <steamId> or without arguments to re-try the last attempt.

crash

Forces the engine to crash.

credits

Prints a list of developers.

debug_ai_schedule

Prints the current schedule behavior tree for the specified NPC on screen.

debug_ai_schedule_print

Prints the current schedule behavior tree for the specified NPC.

debug_aim_info

Prints information about whatever the local player is looking at.

debug_audio_aux_effect

Applies a global DSP effect. Usage: debug_audio_aux_effect <dspName> <gain>

debug_audio_sounds

Prints information about all active server- and clientside sounds to the console.

debug_dump_shader_code

Dumps the glsl code for the specified shader.

debug_font

Displays the glyph map for the specified font. If no arguments are specified, all available fonts will be listed. Usage: debug_font <fontName>

debug_font_glyph_map

Displays the glyph map for the specified font.

debug_glow_bloom

Displays the scene glow texture on screen. Usage: debug_glow_bloom <1/0>

debug_gui_cursor

Prints information about the GUI element currently hovered over by the cursor.

debug_hdr_bloom

Displays the scene bloom texture on screen. Usage: debug_hdr_bloom <1/0>

debug_hitboxes

Displays the hitboxes for the entity under the crosshair, or the entity with the given name (If it was specified.).

debug_light_shadowmap

Displays the depth map for the given light on screen. Call without arguments to turn the display off. Usage: debug_light_shadowmap <lightEntityIndex>

debug_light_sources

Prints debug information about all light sources in the scene.

debug_lightmaps

Displays the lightmaps for the loaded level.

debug_nav_path_end

Sets an end point for a navigation path. Use debug_nav_path_start to set the start point. The path will be drawn in the scene once both points have been set.

debug_nav_path_start

Sets a start point for a navigation path. Use debug_nav_path_end to set the end point.

debug_particle_alpha_mode

Specifies the blend mode arguments for particle systems that use the 'custom' alpha mode. Argument order: <srcColorBlendFactor> <dstColorBlendFactor> <srcAlphaBlendFactor> <dstAlphaBlendFactor> <opColor> <opAlpha>. Blend factor options: zero, one, src_color, one_minus_src_color, dst_color, one_minus_dst_color, src_alpha, one_minus_src_alpha, dst_alpha, one_minus_dst_alpha, constant_color, one_minus_constant_color, constant_alpha, one_minus_constant_alpha, src_alpha_saturate, src1_color, one_minus_src1_color, src1_alpha, one_minus_src1_alpha Operation options: add, subtract, reverse_subtract, min, max

debug_pbr_ibl

Displays the irradiance, prefilter and brdf map for the closest cubemap.

debug_prepass

Displays prepass buffers to screen.

debug_profiling_physics_end

Prints physics profiling information for the last simulation step.

debug_profiling_physics_start

Prints physics profiling information for the last simulation step.

debug_profiling_print

Prints the last profiled times.

debug_render_depth_buffer

Draws the scene depth buffer to screen.

debug_render_info

Prints some timing information to the console.

debug_render_memory_budget

Prints information about the current GPU memory budget.

debug_render_memory_stats

Prints statistics about the current GPU memory usage.

debug_render_octree_dynamic_find

Finds the specified entity in the octree for dynamic objects.

debug_render_octree_dynamic_print

Prints the octree for dynamic objects to the console, or a file if a file name is specified.

debug_render_octree_static_print

Prints the octree for static world geometry to the console, or a file if a file name is specified.

debug_render_scene

Displays scene to screen.

debug_render_stats

Prints information about the next frame.

debug_render_validation_error_enabled

Enables or disables the specified validation error.

debug_ssao

Displays the ssao buffers to screen.

debug_steam_audio_dump_scene

Saves the steam audio scene as OBJ file.

debug_texture_mipmaps

Displays the mipmaps of the given texture. Usage: debug_texture_mipmaps <texturePath>

debug_textures

Prints information about the currently loaded textures.

debug_water

Displays the reflection, refraction and refraction depth map for the given water-entity on screen. Call without arguments to turn the display off. Usage: debug_light_water <waterEntityIndex>

disconnect

Disconnects from the server (if a connection is active), or closes the game if in single player mode.

drop

Drops the player's active weapon.

echo

Prints something to the console. Usage: echo <message>

ent_create

Creates and spawns a new entity with the given class name at the position in the world the player is looking at. Usage: ent_create <className>

ent_input

Triggers the given input on the specified entity. Usage: ent_input <entityName/entityClass> <input>

ent_remove

Removes the specified entity, or the entity the player is looking at if no argument is provided. Usage: ent_remove <entityName/className>

ent_scale

Changes the scale of the specified entity. Usage: ent_input <entityName/entityClass> <scale>

entities

Prints a list of all current serverside entities in the world.

exec

Executes a config file. Usage exec <fileName>

exit

Exits the game.

find

Finds similar console commands to whatever was given as argument.

flashlight

Toggles the flashlight.

fps

Prints the current fps to the console.

getang

Prints the current angles of the local player to the console.

getcamang

Prints the current angles of the camera to the console.

getcampos

Prints the current position of the camera.

getpos

Prints the current position of the local player to the console.

give_ammo

Gives the local player the specified ammunition.

give_weapon

Gives the local player the specified weapon and deploys it.

godmode

Toggles god mode. Requires cheats to be enabled (Or single player mode running).

heartbeat

Instantly sends a heartbeat to the master server.

help

Find help about a convar/concommand.

hurtme

Applies the specified amount of damage to self.

keymappings

Prints a list of all active key bindings to the console.

kick

Kicks the specified player for the given reason. Usage: kick <playerId/playerName> <reason>

list

Prints a list of all serverside console commands to the console.

list_maps

Prints a list of all available list to the console.

listmaps

 

load

 

loc_reload

Reloads all localization files.

log

Adds the specified message to the engine log. Usage: log <msg>.

lua_compile

Opens the specified lua-file and outputs a precompiled file with the same name (And the extension '.clua').

lua_exec

Opens and executes a lua-file on the server.

lua_exec_cl

Opens and executes a lua-file on the client.

lua_help

Prints information about the specified function, library or enum (or the closest candiate). Usage: lua_help <function/library/enum>.

lua_reload_entities

Reloads the scripts for all registered lua entity classes.

lua_reload_entity

Reloads the scripts for the given entity class. Usage: lua_reload_entity <className>

lua_reload_weapon

Reloads the scripts for the given weapon class. Usage: lua_reload_weapon <className>

lua_reload_weapons

Reloads the scripts for all registered lua weapon classes.

lua_run

Runs a lua command on the server lua state.

lua_run_cl

Runs a lua command on the client lua state.

lua_run_gui

Runs a lua command on the GUI lua state.

map

Loads the given map immediately. Usage: map <mapName>

map_build_reflection_probes

Build all reflection probes in the map. Use the '-rebuild' argument to clear all current IBL textures first. Use 'debug_pbr_ibl' to check the probes after they have been built.

map_rebuild_lightmaps

Rebuilds the lightmaps for the current map. Note that this will only work if the map was compiled with lightmap uvs.

nav_generate

Generates a navigation mesh for the current map and saves it as a navigation file.

nav_reload

Reloads the navigation mesh for the current map.

next_weapon

Switches to the next weapon in the player's inventory.

noclip

Toggles noclip mode. Requires cheats to be enabled (Or single player mode running).

notarget

Toggles notarget mode. Requires cheats to be enabled (Or single player mode running).

previous_weapon

Switches to the previous weapon in the player's inventory.

quit

Exits the game.

rcon

Sends the given command to the server and runs it serverside. Usage: rcon <command>

reloadmaterial

Reloads the given material (and textures associated with it). Usage: reloadmaterial <materialFile>

reloadmaterials

Reloads all loaded materials and textures.

render_api_info

Prints information about the current render API to the console.

save

 

screenshot

Writes the contents of the screen into a .tga-file in 'screenshots/'. The name of the file will start with the map's name, or 'pragma' if no map is loaded. After the name follows an ID which is incremented each time. You can use 'screenshot 1' to take a screenshot without the GUI (Ingame only).

setang

Changes the angles of the local player. Requires cheats to be enabled. Usage: setang <pitch> <yaw> <roll>

setpos

Changes the position of the local player. Requires cheats to be enabled. Usage: setpos <x> <y> <z>

shader_list

Prints a list of all currently loaded shaders

shader_optimize

Uses LunarGLASS to optimize the specified shader.

shader_reload

Reloads a specific shader, or all registered shaders if no arguments are given. Usage: shader_reload <shaderName>

sound_play

Precaches and immediately plays the given sound file. Usage: sound_play <soundFile>

sound_stop

Stops all sounds that are currently playing.

startserver

Starts an internet server. Requires a running game.

status

Prints information about the current connection to the console.

strip_weapons

Strips all weapons from the local player.

suicide

Commit suicide.

sv_debug_netmessages

Prints out debug information about recent net-messages.

sv_send

Sends a text message to all connected clients and displays it in the console. Usage: sv_send <message>

sv_send_udp

Sends a text message to all connected clients via UDP and displays it in the console. Usage: sv_send_udp <message>

thirdperson

Toggles between first- and third-person mode.

toggle

Toggles the specified console variable between 0 and 1.

toggleconsole

Toggles the developer console.

udm_convert

Converts a UDM file from binary to ASCII or the other way around.

udm_validate

Validates the specified UDM file.

unbind

Unbinds the given key.

unbindall

Unbinds all keys.

version

Prints the current engine version to the console.

vk_dump_extensions

Dumps all available vulkan extensions to 'vk_extensions.txt'.

vk_dump_features

Dumps all vulkan features to 'vk_features.txt'.

vk_dump_format_properties

Dumps all vulkan format properties to 'vk_format_properties.txt'.

vk_dump_image_format_properties

Dumps all vulkan image format properties to 'vk_image_format_properties.txt'.

vk_dump_layers

Dumps all available vulkan layers to 'vk_layers.txt'.

vk_dump_limits

Dumps all vulkan limitations to 'vk_limits.txt'.

vk_dump_memory_stats

Dumps information about currently allocated GPU memory.

vk_print_memory_stats

Prints information about currently allocated GPU memory to the console.

Game Mounting

Pragma can automatically import assets that can't be found in its native formats from one of the mounted games. The default list of mounted games includes all Valve Source Engine games, as well as a few popular mods, but in some cases you may want to add custom entries. This is currently only possible by editing the list of mounted games in a text-editor manually.

To do so, go to "Pragma/cfg" and open "mounted_games.udm" in a text-editor. Scroll to the end of the file and add the following entry:

"<identifier>"
{
	$bool enabled 1
	"steam"
	{
		$uint32 app_id <appId>
		$string game_path "<gamePath>"
		$bool mount_workshop <mountWs>
	}
	"engine"
	{
		$string name "source_engine"
	}
}

Replace the following attributes:

You can use the other entries as a reference. If you've made a syntax error, it should appear in the console the next time you start Pragma. You can also run the console command udm_validate cfg/mounted_games.udm to ensure the file is syntactically correct.

If your new entry doesn't seem to have any effect, you can start Pragma with the -verbose -console terminal launch parameters, and it should print out a bunch of information about the mounted games and any errors.

 

Mounting custom SFM user folders

If your assets are located in a custom directory under "steamapps/common/SourceFilmmaker/game/", it will not be mounted by default. To mount it, open "Pragma/cfg/mounted_games.udm" in a text-editor, find the "sfm" entry and add the path to the "game_paths" list (replace <your_custom_folder> with the name of your custom directory):

"sfm"
{
	$bool enabled 1
	$string localization_name "mount_game_sfm"
	$int32 priority 950
	"steam"
	{
		$uint32 app_id 1840
		$array game_paths [string][
			"common/SourceFilmmaker/game/usermod/",
			"common/SourceFilmmaker/game/workshop/",
			"common/SourceFilmmaker/game/tf_movies/",
			"common/SourceFilmmaker/game/tf/",
			"common/SourceFilmmaker/game/hl2/",
			"common/SourceFilmmaker/game/left4dead2_movies/",
			"common/SourceFilmmaker/game/platform/",
			"common/SourceFilmmaker/game/portal2/",
			"common/SourceFilmmaker/game/<your_custom_folder>/"
		]
		$bool mount_workshop 1
	}
	"engine"
	{
		$string name "source_engine"
	}
}

Developer Documentation

Developer Documentation

Building Pragma

You can also find these build instructions on the Pragma repository on GitHub.

Build Requirements

Windows
Linux

 

Build Instructions

Launch a command-line interface and clone the pragma repository (with submodules) into a directory of your choice:

git clone https://github.com/Silverlan/pragma.git --recurse-submodules

After that you can simply navigate to the pragma directory and run the python build-script, which will automatically download all dependencies, configure CMake, and build and install the project (this will take several hours):

python build_scripts/build.py --with-pfm --with-all-pfm-modules --with-vr

If you don't need the filmmaker, you can omit the --with-pfm --with-all-pfm-modules arguments, which will significantly reduce the build time and the required amount of disk space.

 

Linux

Before running the build script, you will have to install the following packages:

# Required for the build script
sudo apt-get install python3

# Required for Pragma core
sudo apt install build-essential
sudo add-apt-repository ppa:savoury1/llvm-defaults-14
sudo apt update
sudo apt install clang-14
sudo apt install libstdc++-12-dev
sudo apt install libstdc++6
sudo apt-get install patchelf

# Required for Vulkan
sudo apt-get -qq install -y libwayland-dev libxrandr-dev

sudo apt-get install libxcb-keysyms1-dev
sudo apt-get install xcb libxcb-xkb-dev x11-xkb-utils libx11-xcb-dev libxkbcommon-x11-dev

# Required for GLFW
sudo apt install xorg-dev

# Required for OIDN
sudo apt install git-lfs

# Required for Cycles
sudo apt-get install subversion

# Required for Curl
sudo apt-get install libssl-dev
sudo apt install libssh2-1

# Required for OIIO
sudo apt-get install python3-distutils

 

Once the build script has been completed, you should find the build files in pragma/build, and the install files in pragma/build/install. The install directory should contain everything you need to run Pragma.

If you make any code changes to the core engine code, you can build the pragma-install target to build them. This will also re-install the binaries.

If you make any code changes to a module, you will have to build the module build target first, and then build pragma-install afterwards.

 

Build Customization

Running the build-script with the arguments above will build and install Pragma and the Pragma Filmmaker with all dependencies. Alternatively you can also configure the build to your liking with the following parameters:

Parameter Description Default
--help Display this help  
--generator <generator> The generator to use.

Visual Studio 17 2022 (On Windows)

Unix Makefiles (On Linux)

--c-compiler [Linux only] The C-compiler to use. clang-14
--cxx-compiler [Linux only] The C++-compiler to use. clang++-14
--with-essential-client-modules <1/0> Include essential modules required to run Pragma. 1
--with-common-modules <1/0> Include non-essential but commonly used modules (e.g. audio and physics modules). 1
--with-pfm <1/0> Include the Pragma Filmmaker. 0
--with-core-pfm-modules <1/0> Include essential PFM modules. 1
--with-all-pfm-modules <1/0> Include non-essential PFM modules (e.g. chromium and cycles). 0
--with-vr <1/0> Include Virtual Reality support. 0
--build <1/0> Build Pragma after configurating and generating build files. 1
--build-config <config> The build configuration to use. RelWithDebInfo
--build-directory <path> Directory to write the build files to. Can be relative or absolute. build
--deps-directory <path> Directory to write the dependency files to. Can be relative or absolute. deps
--install-directory <path> Installation directory. Can be relative (to build directory) or absolute. install
--verbose <1/0> Print additional debug information. 0
--module <moduleName>:<gitUrl> Custom modules to install. Use this argument multiple times to use multiple modules.  

Example for using the --module parameter:

--module pr_physx:"https://github.com/Silverlan/pr_physx.git"

 

If you want to create your own binary module, please check out the article on binary modules.

Developer Documentation

Binary Modules

Binary modules allow you to change or extend the behavior of Pragma without having to change the core source code. Binary modules are written in C++ and loaded during runtime using Lua (with some special exceptions). Some example modules are:

 

Installing Modules

If the binary module is available on GitHub and has at least one release, you can use the following console command in Pragma to install the module directly:

install_module <GitHubUser>/<RepoName>

For instance, if you want to install the pr_curl module, simply run install_module Silverlan/pr_curl in the console, which will automatically download the module and install it.

Alternatively, if a binary module comes with prebuilt binaries, you can simply extract the archive to your Pragma installation directory, the file structure in the archive should ensure that its placed in the correct location. Simple modules that consist of a single library file can usually be found in the "modules" directory, while more complex modules (like chromium) reside in their own sub-directory within "modules".

The module can then be loaded with a simple Lua-script:

local moduleName = "chromium/pr_chromium"
local result = engine.load_library(moduleName)
if(result ~= true) then
    console.print_warning("Failed to load \"" .. moduleName .. "\" module: " .. result)
    return
end

The module name is the path to the binary file, without the "modules/" prefix and without the file extension. On Linux the module file also has the "lib" prefix, which has to be omitted as well. For instance, if the module filename is "modules/curl/libpr_curl.so", then the module name should be "curl/pr_curl".

 

Building Modules

If you want to build a module manually, you'll have to first build Pragma. You can then add the module to the build instructions by using one of the following methods:

Method 1) (Recommended)

Open pragma/build_scripts/user_modules.py in a text-editor and follow the instructions to add your module.

After that, simply re-run the build script.

Tip: You can use the --rerun option to make the build script re-use the options used in the previous build.

Method 2)

You can also add the following option when running the build script:

--module <name>:<gitUrl>

For instance, if you want to add the pr_chromium module to the build:

--module pr_chromium:https://github.com/Silverlan/pr_chromium

(You can use the --module argument multiple times if you want to add more than one module.)

 

 

Once the module has been added to the build, you can simply build the pragma-install target. It will build the module and install it automatically. You should then be able to find the module within the "modules" directory of the pragma installation folder.

 

Custom Modules

Setting up your own custom module is very simple and only takes a few minutes using the Pragma module template repository on GitHub, which also includes workflows for automated builds and releases.

To do so, go to the template repository and create a new repository from it:

github_use_template_repo.png

You can choose whatever name you want for the repository, but for consistency it is recommended that it should have the same name as the module, which means:

Some examples are: "pr_chromium", "pr_bullet", "pr_audio_fmod", etc.

Next click "Create repository from template" to generate the repository.

The generated repository now contains a bunch of template files, which still need to be initialized. For that, you will first have to enable write permissions for workflows in the repository settings:

github_workflow_permissions.png

Next, open the file "template_pragma_module.json" on GitHub and edit the values within:

edit_module_template.png

Example:

{
    "name": "Chromium",
    "module_name": "pr_chromium",
    "install_directory": "addons/chromium_browser/modules/chromium/",
    "release_directory": "addons/chromium_browser/"
}

When the module has been built, the binary will be located in "pragma/addons/chromium_browser/modules/chromium/pr_chromium.dll" (or "libpr_chromium.so" for Linux).

The GitHub release will contain all files that are within "pragma/addons/chromium_browser/". Users will be able to simply extract the release over their Pragma installation to install the module.

 

 

Once you have edited the values in the json-file, commit your changes. This will trigger a workflow which will initialize the repository with your values, which should take about two minutes. Simply refresh the page a few times, once you can see the following icons at the top of the readme, it means the initialization was completed:

build_failing.png

The initialization will also trigger the automated build workflows, which may take a few hours to run. Once they have completed, the two icons should turn green, and you should find the compiled binary files available for download for both Windows and Linux in the "Releases" section of the repository.

The build workflows will automatically trigger whenever you push any new commits to the repository and the release binaries will be updated every time. If there are any errors during the build process, the icons will say "failing" again, and you can check the workflow log for more information on what caused the failure.

Once you've set up the repository, you can follow the instructions in the section about building modules to add the module to the pragma build.

Stable Releases

If your module has reached a state that can be considered "stable", you can publish a stable release. To do so, wait for the regular build workflows to complete, then go to the "Actions" tab of your repository and select the "Create Stable Release" workflow, enter a version number and click "Run workflow":

template_module_stable_release.png

This workflow should only take a minute, as it just publishes the latest binaries as a new release.

 

Testing

You can find a simple test Lua-script in the "examples" directory of your module. Follow the instructions in the commented section of the script to install and run it to test the module.

 

Advanced Building

If your module requires additional steps (such as downloading and building external dependencies) before it can be built, you can add those steps to the python script in "build_scripts/setup.py". This script will be executed automatically whenever the Pragma build script is run.

 

Advanced Installation

By default the module binary file will be installed to the "modules" directory of the Pragma installation. If you want to change this behavior, you can do so by editing the "CMakeInstall.txt" file.

Git Changelog

PFM (23-03-31)

Features

Bug Fixes

 

Pragma (23-03-31)

Features

Bug Fixes