Editing Skybox Support

===Abstract===

This page proposes a standard for implementing Skybox Support in Quake 1 engines.  Please be aware that as the Quake 1 source has been released for a significant number of years, there are already diverging implementations.  The proposed standard attempts to cover the most commonly used.  Engines which diverge from the standard should be re-engineered to conform to it.

If you feel I've got anything wrong here, feel free to put it right - it is a Wiki, after all!

===Description===

A Skybox consists of 6 image files, representing the 6 faces of a cube, which is then rendered at a far (but fixed) distance from the observer.  See Quake II (and others) for an example.

===Loading a Skybox===

A skybox is loaded using either the "loadsky" console command or directly from the BSP file (by specifying a skybox name in the worldspawn entry).

Skybox can also be loaded from an ent file but to do that the ent file has to contain the following text:

 {
 "classname" "worldspawn"
 "sky" "foo"
 }

Probably that there should be more lines between the braces, but these two lines are a must.

Call this file "foo.ent" and make sure that this file is in the game directory that is always id1 unless the "-game" command argument is specified.

When you will play "foo.bsp" look up and you will see the "foo" sky (assuming that you have all the six images files of it in "id1/gfx/env" or "id1/env".

===The "loadsky" Command===

This command should take one argument: the skybox base name (see "Naming Convention" below).  A Quake filesystem path is not required.  If the skybox loads successfully, it is immediately used to replace the classic Quake sky.  If the skybox load fails, the current skybox (or the classic Quake sky) is retained.  The standard does not specify what happens if only some of the 6 faces fail to load.

===Loading from Worldspawn===

This is possible to '''automatically''' load all of your favorite skies, assuming that you have all of them in the "id1/gfx/env" directory or folder or in a pak or pk3 file(s), '''automatically''', without having to '''manually''' issue the "loadsky" command every time you either start a new map, level or episode, by using the "worldspawn" QuakeC function '''if''' you have '''both''' the QuakeC (QC in short) source code of the Quake game that you want to play '''and''' a working QuakeC compiler that can compile for you the QuakeC source code of the Quake game that you want to play and produce a valid "progs.dat" file that you should then place it inside the "id1" directory or folder.

Assuming that all of the above is true then: 

In the "worldspawn" QuakeC function, that is usually defined in the "world.qc" file, issue the "loadsky" command of your favorite Quake client or engine that you use by using the "localcmd" C function, that is usually defined in the "defs.qc" file, without forgetting the line feed suffix "\n" to make it to work of course!

localcmd is a C function of every Quake client and engine written in the C programming language and this function can be used in QuakeC without having to mess up with the C source code of your favorite Quake client/engine that you chose to use to play any Quake game.

localcmd allows you to automatically issue every command that you can manually issue it with the console of your favorite Quake client/engine in the game except all the commands that are related to the player that you are controlling with both your keyboard and mouse, like the bf, give, god, fly, notarget and noclip commands.

To issue these commands automatically with QuakeC you need to use the "stuffcmd" C function instead and make sure that the entity first parameter is the player entity that you are controlling in the game.

stuffcmd is also usually defined in the "defs.qc" file like localcmd, it is also every Quake client and engine function written in the C programming language like localcmd and it is also can be used in QuakeC like localcmd.

But both '''luckily''' and '''fortunately''' the "loadsky" command has nothing to do with the player entity that you are controlling in the game with both your keyboard and mouse and this means that the "loadsky" command can be automatically issued with the "localcmd" function and this is both an excellent and wonderful fact because the "localcmd" function is both much simpler and easier than the "stuffcmd" function since the "localcmd" function does not require a player entity as a first parameter unlike the "stuffcmd" function which does require!

'''For example''' if you want to always see a blue sky no matter what map, level, episode and skill you play then make sure that you have all the six images files of a blue skybox in the "id1/gfx/env" directory or folder or in a pak or pk3 file(s) and then in the "worldspawn" QuakeC function, that is usually defined in the "world.qc" file, somewhere just insert/inject the following line of code:

 localcmd("loadsky bluesky\n"); //I want to see a blue sky all the time

If you have a large collection of many different skies all in the "id1/gfx/env" directory or folder or in a pak or pk3 file(s) then you may want to use the "self.model" variable to know which sky to load for which level and map.

For example if you love to see night in the start map where you need to choose skill and episode and see blue sky in every other map then make sure that you have all the six images files of a night and blue skyboxes in the "id1/gfx/env" directory or folder or in a pak or pk3 file(s) and then in the "worldspawn" QuakeC function, that is usually defined in the "world.qc" file, somewhere insert/inject the following piece of code:

 if (self.model == "maps/start.bsp")
     localcmd("loadsky night\n"); //I love to see night when I have to choose skill and episode
 else
     localcmd("loadsky bluesky\n"); //I love to see blue sky when I am killing monsters and finding secrets

With Fteqcc you can also do this instead:

 switch (self.model)
 {
     case "maps/start.bsp": localcmd("loadsky night\n"); break; //I love to see night when I have to choose skill and episode
     default: localcmd("loadsky bluesky\n"); break; //I love to see blue sky when I am killing monsters and finding secrets
 }

Use the "skill" global variable instead of the "self.model" variable if you have at least 4 skies each for Easy, Normal, Hard and Nightmare skills.

If you do have them then you may want in the "worldspawn" QuakeC function, usually defined in the "world.qc" file, somewhere insert/inject the following piece of code:

 if (skill == 0) localcmd("loadsky easy\n"); //Load the "easy" sky if I am playing the game on the "Easy" skill
 else if (skill == 1) localcmd("loadsky normal\n"); //Load the "normal" sky if I am playing the game on the "Normal" skill
 else if (skill == 2) localcmd("loadsky hard\n"); //Load the "hard" sky if I am playing the game on the "Hard" skill
 else if (skill == 3) localcmd("loadsky nightmare\n"); //Load the "nightmare" sky if I am playing the game on the "Nightmare" skill

With Fteqcc you can also do this instead:

 switch (skill)
 {
     case 0: localcmd("loadsky easy\n"); break; //Load the "easy" sky if I am playing the game on the "Easy" skill
     case 1: localcmd("loadsky normal\n"); break; //Load the "normal" sky if I am playing the game on the "Normal" skill
     case 2: localcmd("loadsky hard\n"); break; //Load the "hard" sky if I am playing the game on the "Hard" skill
     case 3: localcmd("loadsky nightmare\n"); break; //Load the "nightmare" sky if I am playing the game on the "Nightmare" skill
 }

Never forget break; at the end after each case because otherwise all below cases until break; will be executed as well and this is an error whose result is a bug in the game!

This is both an excellent and wonderful way to know what is the skill of the Quake game that you are playing without having to manually bring down the console by pressing the tilde key on your keyboard and then type and enter the word "skill".

Just look up on the sky and the sky will tell you what is the skill of the game that you are playing!

This may also give you the appropriate feeling if you both think and believe that blue sky means easy game, green sky means that the game is neither easy nor hard, red sky means hard game and so on (What do you think that the sky of the nightmare skill should look like? I am leaving this question to you to answer!).

But of course that after inserting/injecting the piece of code with any text editor, like Notepad, make sure that you have saved all the changes that you have made to the file, that usually should be world.qc, before closing your favorite text editor (for me Notepad is my favorite text editor because it is so both fast, lightweight and very easy to use and it is also built-in in Windows 10 which means that I don't have to download and install it every time I install Windows 10).

After saving all the changes and closing the text editor you need to compile your QuakeC source code with a working QuakeC compiler.

Nowadays this is very well known that all the QuakeC developers, coders and programmers use either FTEQCC or GMQCC to compile QuakeC code.

But between the two mentioned QuakeC compilers above, FTEQCC is my favorite QuakeC compiler because it has a GUI version, and in addition to that FTEQCC is also both fast, lightweight and very easy to use exactly like Notepad and in addition to that I don't have to suffer from compiling C source code unlike GMQCC that does not have even a GUI version at all!

Yes indeed I personally love all software that are both fast, lightweight and very easy to use!

But of course that you should choose the software that best fits your needs.

If you are using a QuakeC compiler that is a console application (that is using Command Prompt) then make sure that the executable file of the chosen QuakeC compiler is in the same directory or folder where all the source QuakeC files are before executing the chosen QuakeC compiler that should compiles your QuakeC code.

If you are using the GUI version of FTEQCC, usually called "fteqccgui.exe" for 32 bit windows operating system or "fteqccgui64.exe" for 64 bit windows operating system, then you can place the executable file wherever you want but when launching the GUI version of FTEQCC you must find and open the "progs.src" file!

The "progs.src" file should be in the same directory or folder where all the QuakeC source files are.

The "progs.src" file must come with every QuakeC source code and every QuakeC source code must include a "progs.src" file because the "progs.src" file lists all the QC files that have to be compiled in the order which is obviously indeed both essential and vital information for all the QuakeC compilers which obviously must know what QC files to compile and in what order to compile them.

If you have successfully compiled your QuakeC source code with the help of your favorite QuakeC compiler, that you chose to use, then your favorite QuakeC compiler, that you chose to use, should have created a "progs.dat" file, Usually '''outside''' of the directory or folder where all the QuakeC source code files, that you have compiled with the help of your favorite QuakeC compiler, are.

Make sure that this "progs.dat" file is inside the "id1" directory/folder where all the pak and pk3 files of the Quake game, that you want to play, should be unless you execute your favorite Quake client/engine with a "-game" command argument of course.

Of course that the directory/folder mustn't be "id1" of course if you execute your favorite Quake client/engine with the "-game" command argument but it should be X instead if the "-game X" command argument is specified before starting the Quake client/engine where X can be any word or name of a Quake game that you want to play.

If everything was done both right and correctly from the start to the end and the "progs.dat" file, that was created by your favorite QuakeC compiler, is really inside the right or correct directory or folder then you can play the game with all your favorite skies and they will be loaded '''automatically''' as you want! And this means that you don't have to manually issue the "loadsky" command anymore every time you either start a new map, level or episode which is indeed much more both convenient and better quality of life!

'''If''' you have the source (map and wad) files of the bsp files of the Quake game that you want to play, then another option is to just set the sky of each map file to whatever sky you want before you compile all your map and wad files into playable bsp files and then put all of them in the "id1" directory/folder or X directory/folder if you execute your favorite Quake client/engine with the "-game X" command argument where X is any word or name of a Quake game.

Of course that you will need the appropriate editor to edit your map files and the appropriate compilers to compile both your map and wad files into playable bsp files.

Another option is to change the sky of the Quake level that you want to play directly by editing the bsp file of the Quake level with any working hexadecimal editor.

'''But''' go for this option '''as a last resort only if''' you do'''n't''' have any source files to edit and compile '''at all'''! Because directly editing a bsp file is like directly editing a progs.dat file is like directly editing an executable (exe in short) file is like directly editing a dll file is like directly editing any binary file or byte code that was created by a compiler and this is very well known that editing such files with any hexadecimal editor is very risky and unsafe operation since the language that these files use to communicate with the software that reads them is very hard for a human to understand and this is very hard to achieve the goal this way in general and any little mistake, wrong edit in the file, if you modified in the file any byte that should not be modified to achieve your purpose, this action will instantly make the file '''both unplayable and unusable''' anymore! And undoing your mistakes, to make the file both playable and usable again like before, is impossible if you don't remember what were all the original bytes before you overwritten them with yours!

So if you really go for this option and you are about to and going to edit a bsp file, which was created by a wad and map compiler, with your favorite hexadecimal editor then don't forget to '''first''' backup your bsp file by copying it into a backup directory/folder and if you will do any mistake and as a result the modified bsp file is ruined and unplayable anymore then instead of trying to fix it just delete the ruined and unplayable bsp file and then use copy your backup bsp file and try again.

Repeat this process as many times as needed until you find out what has to be done and what not and you have successfully achieved your purpose.

This option is indeed and obviously a lot of trial and error until you find out what bytes you should modify and what bytes should remain unchanged and indeed you will have to spend a lot of time until you find it!

===Unloading a Skybox===

Issuing the "loadsky" command without any arguments will unload the current skybox and revert to the classic Quake sky.  Engine coders may implement an "unloadsky" command if they wish, but this is not a requirement and should not be relied on.

===Image Formats===

Skyboxes should be provided as either TGA or PNG files.  All 6 faces should be same format (should engines be required to support a possibility that they are different formats?)  The images should be sized so that they are powers of 2: 256 x 256, 512 x 512 or 1024 x 1024 are common sizes.  The 6 faces need not be the same size.

===Naming Convention===

Each Skybox face name is composed of two components: the base name and a suffix indicating which face the image relates to.

The base name should be strictly alphanumeric, and should not contain spaces.  Only the base name is used for loading.

The suffix should be either of "bk" (back face), "ft" (front face), "lf" (left face), "rt" (right face), "up" (up face) or "dn" (down face).

Optionally, there may be an underscore ("_") between the base name and the suffix.  Engines should be capable of successfully loading a skybox (1) where the underscore is present in both the load command and the name, (2) where the underscore is absent in the load command but present in the name, and (3) where the underscore is absent in both.

===Filesystem===

Skyboxes may be stored in either the native OS filesystem or in a PAK file, and loading from either should be supported in any implementation.  All filesystem references are relative to the base game directory (e.g "ID1").

A skybox may be loaded from any of "gfx", "env" or "gfx/env"; implementations should support loading from all 3.  Skyboxes should not be present in "textures" (nor in any subdirectory thereof).

All 6 components of a skybox should be in the same directory.