fegennari/3DWorld

3DWorld Blog: https://3dworldgen.blogspot.com

3DWorld is a cross-platform OpenGL-based 3D Game Engine that I've been working on since I took the CS184 computer graphics course at UC Berkeley in 2001. It has the following features:

• 3D graphics functions, classes, and wrappers around OpenGL
• Shader generator/processor with hot reload
• Procedural content generation for terrain, vegetation, cities, building interiors and exteriors, etc.
• Procedural universe generator with galaxies, stars, planets, moons, etc.
• Procedural voxel 3D terrain generation with realtime user editing
• Terrain generator including various noise functions, erosion, realtime user editing, heightmap read/write
• Procedural building (interior and exterior), road, and city generation
• Physics simulation for primitive object types and others (> 10K dynamic objects)
• Realtime day/night cycle with weather (rain, snow, hail, wind, lightning)
• Physically based materials with reflection and refraction
• Dynamic shadows, ambient occlusion, up to 1024 dynamic light sources, postprocessing effects
• Skeletal animation and procedural animation
• Built-in first person shooter game "smiley killer"
• Build-in spaceship + planet colonization game
• Building open world item collection and zombie gameplay mode
• Computer AI for players in the FPS game, building gameplay, and ships in the universe game
• Importer for Lightwave object file, 3DS formats, and Assimp for other file formats
• Reading support for textures: JPEG, PNG, BMP, TIFF, TGA, DDS
• Optimized for fast load and realtime rendering of large models (> 1GB of vertex/texture data)

I converted the project from svn to git at commit 6607. Most of the code is written in C++, with GLSL for shaders. This is intended to be a cross-platform project. Microsoft Visual Studio 2022 project files are included. A linux/gcc makefile is also included, but is more experimental. See README.linux for more details. The project should build under gcc on linux with some work, but it's been a while since I tried this. I have an old makefile that is out of date, but may not take too much work to fixup and make it usable.

Be warned, this is a large repository, currently about 1GB. I've included source code, config files, textures, sounds, small models, lighting files, scene data, heightmaps, and project files. This repo does not contain the large model files used in some scenes, you'll have to download these separately. This means that some of the scene config files won't work because they can't find their referenced data. The current list of dependencies is:

• OpenGL 4.5 (Should come with Windows 8/10/11 latest graphics drivers)
• OpenAL 1.1 (optional) (System Install: https://www.openal.org/downloads/ or you can try the newer openal-soft: https://github.com/kcat/openal-soft)
• freeglut-2.8.1 (Current 3.0 version probably works: https://sourceforge.net/projects/freeglut/)
• freealut-1.1.0 (optional) (One version is here: https://github.com/vancegroup/freealut)
• zlib-1.2.11 (You can download a newer version from here: https://zlib.net/)
• glew-2.0.0 (2.1.0 probably works as well: http://glew.sourceforge.net/)
• gli (Latest version: https://github.com/g-truc/gli / header only, included in dependencies directory)
• glm-0.9.9.0 (Latest version: https://glm.g-truc.net/0.9.9/index.html or https://github.com/g-truc/glm / header only, included in dependencies directory)
• libpng-1.2.20 (optional) (My version is very old; Latest version: https://libpng.sourceforge.io/index.html); Can be replaced with stb_image in most cases, except for map image export.)
• libtiff-4.3.0 (optional) (Latest version: http://www.simplesystems.org/libtiff/)
• Assimp (optional) (See build instructions at https://github.com/assimp/assimp/blob/master/Build.md ; The vcpkg build instructions are probably the easiest.)
• libtarga (source included)
• STB headers: stb_image, stb_image_write, stb_dxt (source included)

I've included stripped down versions of most of these libraries in the dependencies directory. I removed all large files that aren't required by 3DWorld, in some cases even examples/tests/documentation. These have been built with MS Visual Studio 2022 Community on Windows 11. If you want to use these, you'll need to copy the directories to the root directory and rebuild any libraries needed for other versions of Windows or Visual Studio. If you clone/install vcpkg it should be at the same level as the 3DWorld directory.

Note that many of these dependencies are old and could be replaced with newer libraries. I've been concentrating on adding content and I'm not too interested in this. Freeglut should probably be replaced with SDL, and the image libraries with STB or DevIL. (STB is used as a fallback but doesn't support all of the images used.)

If you want to build 3DWorld, you can use the projects in the dependencies/ folder, or download and build them yourself and change the project settings to use them. I currently use the x64 MS Visual Studio 2022 Community build target for 3DWorld, but the win32 build target also works. The MSVS 2019 project 3DWorld_msvs2019.vcxproj is currently out of date but can possibly be made to work. It should compile and run in 32-bit mode if you copy the DLLs from the lib64/ folder into the root of the repo and make some other project settings changes.

If you have linux, you can try to build using the provided makefile. The file README.linux should be helpful. I've gotten 3DWorld to build and mostly run on Ubuntu 18.04 with gcc 7 and Ubuntu 20.04 with gcc 9.

3DWorld takes a config filename on the command line. If not found, it reads defaults.txt and uses any config file(s) listed there. Some of these congig files include models such as the Sponza Atrium, Stanford Dragon, sportscar, etc. These files are too large to store in the git repo. I've attempted to have 3DWorld generate nonfatal errors if the models can't be found. Many of the larger models can be found at the McGuire Computer Graphics Archive: http://casual-effects.com/data/

I've packaged up the 3D models that are too large for the GitHub repo and put them on Google Drive here: v7, 732MB, for latest release: https://drive.google.com/file/d/1T2fPwiJ7x2ga8hRPrLAZDlkWZMh-NsVp/view?usp=drive_link

And the newer file: v9, 853MB, for git head: https://drive.google.com/file/d/11R-LCFb6VEylX7ncPgkUrgZN01zz88P2/view?usp=drive_link

Some of these models are stored in 3DWorld's internal format and should not be reused in other projects. Others come from websites such as Mixamo. There is also a textures directory with additional textures used with building interiors that can be merged with the project textures directory.

System requirements:

• Windows 8/10/11; Linux when using the makefile with gcc.
• Microsoft Visual Studio 2019 or 2022. The professional or community version is needed for OpenMP support. You can also try to use gcc on linux.
• A relatively new generation of Nvidia or AMD GPU (Runs on my laptop with Intel graphics, but at 12-20 FPS)
• At least 8GB system memory for the larger scenes
• At least 4GB GPU memory for the larger scenes; My GPU has 12GB of memory

Troubleshooting: It seems like some systems (AMD cards in particular) require an OpenGL core context. This can be selected by adding "use_core_context 1" in the config file. This can also be enabled in scene_config/config_post.txt, which is a file that applies after reading all other top-level config files. In some situations (some Nvidia cards), using a core context can be slower, which is why I don't have it enabled by default.

Useful Keys (see readme-keys.txt for more key bindings):

• a,s,d,w: Movement
• q,e: Change weapon (gameplay mode)
• 'space': Jump/fire
• 'esc': Quit
• 'tab': Onscreen menu (navigate with arrow keys and 'X' to switch menus)
• b: Enable objects/physics/AI (for ground mode and universe mode gameplay)
• F1: Switch between ground/universe/tiled terrain modes
• F2: Toggle gameplay mode
• m: Toggle fullscreen mode
• h: Toggle flight move
• v: Change camera mode (crystal ball/orbit vs. first person)
• V: Toggle mouse look
• K: Toggle overhead map mode
• x: Pause
• Mouse Left: Turn/Action
• Mouse Right: Fire

I currently have this repo up for educational purposes under the GPLv3 license. Some sub-modules are available with other licenses compatible with commercial use in my GitHub account. It's not meant as a commercial tool and I'm not trying to make money here. I'm also not looking for others to work on the project at this stage, though I'm accepting feedback, bug reports, and suggestions. Maybe things will change if I decide to make a real game out of this. If you would like to use something here for your project, please let me know.

There is no further documentation for 3DWorld. However, I do have a blog that includes descriptions of the algorithms and lots of screenshots: https://3dworldgen.blogspot.com

Please do not send me bot/AI generated pull requests. Please do not make suggestions related to the dependencies directory. This is included as a reference and the user is expected to update and/or build these libraries themselves.

Here are some screenshots linked from my blog:

This is a procedurally generated factory interior with machines, tanks, catwalks, ladders, and pipes. (config_heightmap.txt)

This is the interior of a 7 level procedurally generated mall interior. (config_heightmap.txt)

Here is a procedurally generated mall food court with tables and chairs, and stores to the sides. (config_heightmap.txt)

Here is a retail area of a building with racks of shelves. Buildings can contain tens of thousands of interactive objects the player can take and carry around. (config_heightmap.txt)

Cameras placed in other rooms show realtime video feeds on security monitors. (config_heightmap.txt)

Zombies (with path finding and other AI behaviors) walking around and falling into an indoor pool. The water water surface has ripples, splashes, reflections, and refractions. (config_heightmap.txt)

Parking garage with parked cars and sprinkler pipes routed on the ceiling. (config_heightmap.txt)

Procedural building basement with people, indirect lighting, and pipes routed along the ceiling. (config_heightmap.txt)

Procedural residential neighborhood with office buildings in the backround. There are cars and people both on the sidewalks and inside buildings. (config_heightmap.txt)

Procedural building interior - a library with procedurally generated books. (config_heightmap.txt)

Procedurally generated houses and office buildings with full interiors. (config_heightmap.txt)

Reflective (metal), refractive (glass), emissive, and translucent spheres in night time scene with indirect lighting. Drawn in realtime; spheres can be moved interactively. (config_white_plane.txt)

Procedural city with buildings, roads, cars, and pedestrians. (config_heightmap.txt)

Procedural city at night with bridge in the foreground. (config_heightmap.txt)

Early procedural city with pine trees.

Early procedural city.

Terrain using domain warp noise