# Technical Documentation: supertuxkart/stk-code

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/supertuxkart/stk-code)

### Overview (README.md)

# SuperTuxKart
[](https://github.com/supertuxkart/stk-code/actions/workflows/linux.yml)
[](https://github.com/supertuxkart/stk-code/actions/workflows/apple.yml)
[](https://github.com/supertuxkart/stk-code/actions/workflows/windows.yml)
[](https://github.com/supertuxkart/stk-code/actions/workflows/switch.yml)
[](https://web.libera.chat/?channels=#supertuxkart)

SuperTuxKart is a free kart racing game. It focuses on fun and not on realistic kart physics. Instructions can be found on the in-game help page.

The SuperTuxKart homepage can be found at <https://supertuxkart.net/>. There is also our [FAQ](https://supertuxkart.net/FAQ) and information on how get in touch with the [community](https://supertuxkart.net/Community).

The latest release binaries can be found [here](https://github.com/supertuxkart/stk-code/releases/latest), and those of preview releases [here](https://github.com/supertuxkart/stk-code/releases/preview).

## Hardware Requirements
Any hardware that supports OpenGL >= 3.3 or OpenGL ES >= 3.0 should be able to run SuperTuxKart. For Android, Android 5.0 or greater is required.

This includes dedicated GPUs from Nvidia or AMD released after 2010, integrated GPUs released after 2012 and Android phones released after 2014.

The game will run on some very weak devices, but a better GPU allows to run smoothly using higher quality graphics and a higher resolution, and a better CPU helps to keep a smooth playing experience in online multiplayer.

Please check the "What are the hardware requirements?" question in our [FAQ](https://supertuxkart.net/FAQ) for more information.

## License
The software is released under the GNU General Public License (GPL) which can be found in the file [`COPYING`](/COPYING) in the same directory as this file.

---

## Building from source

Building instructions can be found in [`INSTALL.md`](/INSTALL.md)

## Contributing code

**To contribute code to the official STK repository, please review the ['How to contribute code'](https://supertuxkart.net/How_to_contribute_code) guide.** It contains important guidelines to make the process smoother and maximize the chances that your contribution is accepted.

## 3D coordinates
A reminder for those who are looking at the code and 3D models:

SuperTuxKart: X right, Y up, Z forwards

Blender: X right, Y forwards, Z up

The export utilities perform the needed transformation, so in Blender you just work with the XY plane as ground, and things will appear fine in STK (using XZ as ground in the code, obviously).

---

### Doc Graphics Views (`doc/graphics_views.txt`)

Graphics debug views
====================

There are some graphics debug views, to be used both by artists when developing,
and by users when reporting bugs.

These should be available in normal (non-artist) mode
to enable easier bug reports (go there, press this key, screenshot)
without requiring editing the UTF-32 config files (which is inconvenient, most editors
do not support that weird encoding).

They don't give gameplay advantages like the item keys, so there should be little harm
leaving them available. Accidental keypresses ought to be minimized by their location.

Home	- wireframe view
End 	- mipmap visualization (is a texture too high or low resolution, red = too high)
Del	- normal view
PgDown	- SSAO view
PgUp	- light view
Ins	- shadow view
ScrlLock - displacement view

---

### Doc Graphics Xml (`doc/graphics_xml.txt`)

Graphics GSOC XML additions
===========================

This document will list in depth all new XML values added during the graphics GSOC, for use 
by the blender exporter scripts.

Glow colors
-----------

The glow colors for nitro bottles and boxes are settable in stk_config.xml.
They are three-value RGB colors.

Example: <glow-colors nitro="0 0 255" box="255 0 0" />


Particle wind
-------------

Particles may be affected by wind. This is used with the snow particles.

Flips is a boolean controlling whether each particle will spin about its own two axis.
It is only applicable to symmetric textures, such as snow flakes.

Speed is a float in no real units.

Example: <wind speed="0.16" flips="Y" />


Forced bloom objects
--------------------

Any object may be marked as forced bloom. This will include the object in the bloom pass 
regardless of its brightness.

Example: forcedbloom="Y" inside the <object> tag, in scene.xml.

Forced bloom objects may optionally include a multiplier, ranging from 0.5 to 10:
bloompower="2.5"


Glowing objects
---------------

Any object may be marked as glowing. The glow is a RGB value.

Example: glow="0 255 0" inside the <object> tag, in scene.xml.


Caustics
--------

A material effect, ie GE_CAUSTICS, to mark a texture as receiving caustics. To be used
for the ocean floor, puddle floor, etc.

Example: graphics-effect="caustics" in materials.xml.


Refractions/reflections
-----------------------

A per-object boolean flag, typically set for subsea windows or the ocean surface. 

Example: displacing="Y" in the <object> tag in scene.xml.



	Per-track tags
	--------------

These are all specified inside track.xml, among the track's author, music, etc.

Cloud shadows
-------------

Boolean whether to have the sun blocked by cloud shadows, moving with the wind.
Disabled by default.

The effect is completely fake, doesn't correspond to any real or simulated clouds, but 
nobody's checking, so it looks nice.

Example: clouds="Y" inside the <track> tag.


Bloom
-----

Boolean whether to enable global bloom for this track. Enabled by default.

Example: bloom="Y" inside the <track> tag.


Bloom threshold
---------------

Float that specifies the minimum luminance needed for a pixel to participate in the bloom.
The default is 0.75.

Example: bloom-threshold="0.75"


Lens flare
----------

Boolean that specifies whether a lens flare is shown when the player looks at the sun.
The strength and angle depend on the relation of the camera to the sun. Disabled by default.

Example: lens-flare="Y"


Dynamic shadows
---------------

Boolean on whether this track should use dynamic shadows. Enabled by default.

If disabled, the fallback fake kart shadows will be used.

Example: shadows="N"


God rays
--------

Boolean on rendering god rays when the player looks at the sun. Disabled by default.

Example: god-rays="Y"


Displacement speed
------------------

Float on the relative speed of any displacing objects in this level. Default 1.0.
2.0 = double speed, 0.5 = half speed, etc.

Example: displacement-speed="1.5"


Caustics speed
--------------

Float on the relative speed of any caustics objects in this level. Default 1.0.
2.0 = double speed, 0.5 = half speed, etc.

Example: caustics-speed="1.5"


Fog
---

The density tag was removed (it was unused anyway).
The max, height start, and height end tags were added.

fog-max: float capping the amount of fog to apply, default 1.0.
fog-start-height: minimum height of fog, default 0.0.
fog-end-height: maximum height of fog, default 100.0.

The fog scales smoothly according to both the height, and the distance from
camera.

---

### Doc Pipeline Overview (`doc/pipeline_overview.txt`)

New pipeline overview
=====================

Organized by RTTs
-----------------

To color:
	- initialize the glow representations (no rendering yet)
	- render the 3d skybox, if any (includes the usual skybox)

To the MRT (color, normals, depth):
	- solids

To quarter1:
	- glowmap

To various shadow maps:
	- shadows

To tmp1:
	- lights

To color:
	- lights from tmp1 are multiplicatively blended
	- skybox if there is no 3d skybox
	- lens flare/god rays occlusion query (no rendering)
	- solid post-processing
	- transparents

To displace:
	- displacing nodes, if any

To the screen:
	- the post-processing chain
	- GUI


Organized by passes
-------------------

Init:		glow init -> 3d skybox
Main:		solids -> glows -> shadows -> lights -> occlusion query -> solid PP
Transparent:	transparents -> displacing -> PP
GUI:		gui

---

### Lib Irrlicht Doc AesGladman (`lib/irrlicht/doc/aesGladman.txt`)

The Irrlicht Engine may be compiled to provide support for AES encrypted files. The implementation used by Irrlicht is provided by Dr Brian Gladman. The license for these files (including AES, a PRNG, SHA, and other algorithms) is as follows

/*
 ---------------------------------------------------------------------------
 Copyright (c) 2002, Dr Brian Gladman <                 >, Worcester, UK.
 All rights reserved.

 LICENSE TERMS

 The free distribution and use of this software in both source and binary
 form is allowed (with or without changes) provided that:

   1. distributions of this source code include the above copyright
      notice, this list of conditions and the following disclaimer;

   2. distributions in binary form include the above copyright
      notice, this list of conditions and the following disclaimer
      in the documentation and/or other associated materials;

   3. the copyright holder's name is not used to endorse products
      built using this software without specific written permission.

 ALTERNATIVELY, provided that this notice is retained in full, this product
 may be distributed under the terms of the GNU General Public License (GPL),
 in which case the provisions of the GPL apply INSTEAD OF those given above.

 DISCLAIMER

 This software is provided 'as is' with no explicit or implied warranties
 in respect of its properties, including, but not limited to, correctness
 and/or fitness for purpose.
 ---------------------------------------------------------------------------
*/

---

--- METRICS ---
- Files Extracted: 5
- Estimated Token Budget: ~2409 tokens
- Canonical Reference: https://codewiki.google/github.com/supertuxkart/stk-code