In-depth documentation

[Josh]

As discussed in yesterday's meeting, I am very interested in authoring tutorials that are meant to go beyond just learning the documentation for specific commands and answer the question of "how do I make a game"?

I think the challenge here is to devise an overall structure for the articles, so they are a sequence of lessons and not just answers to random questions.

So I am putting the question to you, how do you think this should be structured? What are the titles of the actual articles that should be written, and what order should they be listed in? I'm looking for something like this:

1. XXXXXXXXXX
   1. XXXXXXXXXX
   2. XXXXXXXXXX
   3. XXXXXXXXXX
2. XXXXXXXXXX
   1. XXXXXXXXXX
   2. XXXXXXXXXX
   3. XXXXXXXXXX
   4. XXXXXXXXXX
   5. XXXXXXXXXX
3. XXXXXXXXXX
   1. XXXXXXXXXX
   2. XXXXXXXXXX
4. XXXXXXXXXX
   1. XXXXXXXXXX
   2. XXXXXXXXXX
   3. XXXXXXXXXX

Let's discuss ideas.

[Thirsty Panther]

I think your structure is good.

Here is an example from GameDev.tv structure which mirrors what you have in mind.

[Josh]

Good, but we need a full series. What should it look like? Thoughts, everyone?

[Josh]

@WazMeister, I need your opinion! Now is your time to tell me what you need.

[Josh]

Something like this:

1. Tutorials
   1. Editor Interface
      1. Textures
      2. Materials
         1. PBR
         2. Tessellation and displacement
      3. Models
      4. Shaders
   2. Level Design
      1. Models
         1. Translate tool
         2. Rotate tool
         3. scale tool
      2. Brushes
         1. Creation
         2. Edit faces
            1. Tessellation and displacement
            2. Material painting
         3. Edit vertices
      3. Environment settings
   3. Gameplay
      1. Components
      2. Component properties
      3. Flowgraph
      4. Exposing component properties from code to the editor

[Thirsty Panther]

1. Tutorials
   1. Editor Interface
      1. Textures
      2. Materials
         1. PBR
         2. Tessellation and displacement
      3. Models - How import, How convert to Mdl, Apply a texture, Load animations, Remesh, collision mesh, LOD
      4. Shaders
      5. Particles
      6. Probes
      7. Decals
      8. Project tab navigation  and uses of.
      9. Scene tab navigation and uses of.
      10. How to add a component to a model.
      11. How to run your game (Lua).
      12. Project Manager- How creat a project, update a project, use a template.
      13. Terrain- How to create, How to sculpt, paint, smooth, add foliage, rocks etc 
      14. World settings- How to modify ambient light, How to add a skybox, How to add fog, How to add effects.
      15. Asset Library- how to add models, textures and sounds from the asset library.
      16. Options menu- How to set general settings, video, veiwport, projects, material and project settings.
      17. Publish- How to finalize your game.
   2. Level Design
      1. Models
         1. Translate tool
         2. Rotate tool
         3. scale tool
         4. Carve tool
         5. Hollow tool
      2. Brushes
         1. Creation
         2. Edit faces
            1. Tessellation and displacement
            2. Material painting
         3. Edit vertices
      3. Environment settings
      4. Global ilumination
      5. How to build a navmesh
   3. Gameplay
      1. Components
      2. Component properties
      3. Flowgraph
      4. Exposing component properties from code to the editor
      5. Moving platforms, sliding doors.
      6. Push button/ switches to open/close a door, switch a light on and off.
      7. "E" to grab/ hold objects.
      8. HUD for gun sights, health, ammo and score
      9. Health kit - health regeneration
      10. Ammo box - ammo replenishment
      11. Raycast for guns
      12. projectiles
      13. High score table
      14. How to change maps
      15. Simple quest system eg kill 10 rats
      16. Simple Inventory system
      17. Simple crafting system
      18. Teleport system
      19. Security camera (camera to texture)
      20. Enemy spawning
      21. Different sounds (footsteps) on different surfaces.
      22. Gravity gun
      23. Jetpack on player.
      24. Hand gernade with damage and physics effect.
      25. Ladder climbing.
      26. Weather effects, Rain/snow.
      27. Picking up a new weapon.
      28. NPC dialog system.
      29. Basic skill tree.
      30. Swimming when in  water.
      31. Checkpoints.
      32. A simple turret that shoots at the player.

[Josh]

@Thirsty PantherThank you for your detailed response. That is extremely helpful.

[Thirsty Panther]

I cant take all the credit for the gameplay ideas. I trawled thru an old Leadwerks topic where everyone was requesting what they wanted a tutorial on.

I didn't ask for any 2D tutorials as I think Ultra Engine's strenght is in 3D.

 

[khotan]

Thanks and it is very good idea !

I am for somewhat as snippet of codes for showing to "how i do make a game" on level from basic to advanced

Because of beginners need all that to start something with Ultra Engine.... Hope that will make this one !

Good luck and I am looking forward to this

Happy coding !

[Josh]

Okay, so should these tutorials be programming tutorials, or should they use a component that has been added into the default components, and explain what all the properties do? Are they "how to code" or are they no-code tutorials that show how to set up these situations?

[Thirsty Panther]

I think most of them lend themselves to being components. Things like health kits and ammo boxes for example. The advantage of this approach is that if the user is not that interested in learning "programming" then they can just add the component and move on. For others who do want to expand their programming knowledge a fuller explanation of how you developed the component would be helpful. They could then alter or modify them for other purposes. 

There are others that I think would benefit from a fuller explanation. Inventory and crafting systems, I think, would be hard to do as a single component and would require a "how to code" approach.

[khotan]

Yes for quickly to learn with purpose is training video because of a lot with codes as it is a fuller explanation. And shorter explanation as basic tool in text with images on how to do my game. Maybe a suggestion is to create a section for tutorial to community where others programmers share their tutorials as well, what do you think of that ? Because you can't do it all tutorial, right ?

[Dreikblack]

12 minutes ago, khotan said:

Maybe a suggestion is to create a section for tutorial to community where others programmers share their tutorials as well,

For now i just post my tutorials in blogs, but more dedicated section would be better 

 

[Josh]

I am thinking the tutorials should be divided up into separate games, rather than trying to make one game with every feature.

The first tutorials should be code-centric and just involve programming the main.lua or main.cpp file. All assets used will be loaded from a github repository, with URLs in the code, so there is nothing to download:

• Pong3D
• Flappy3D
• Asteroids3D

More advanced games will use the entity component system. At this point, each game will have an official template included in the available project templates you can create. These templates will contain unique components for each game, because I don't think I can make every game in one set of components. The artwork will be mostly filler / abstract with a few models from Sketchfab.

• Simple FPS game
• Simple RPG game

etc.

Each game will be divided into about eight different tutorials that focus on a different feature.

[khotan]

Nice it is a good to start and to learn those all

Keep it up as well !

[Josh]

I think I have figured out the primary conflict in all of this.

People ask for tutorials like "how do I pick up a weapon?", or "how do I add a jetpack"? The problem is there is no one way to do these things, and your implementation of one feature will affect other features in the game. These features are never as self-contained as people think they are. So effectively, these types of requests amount to "make a game with every feature, but I can't define the game I want, but it should be every game packed into one", and this is impossible.

The solution is to treat each game as an isolated system and not try to make all features of all the game tutorials interchangable. That's the only way it can be done.

So my idea is three example games in a cartoonish style:

• Marble game
  • Controls
  • Collect rings for score
  • Moving and rotating platforms / obstacles
  • Level changing
  • Steam high score table
  • Multiplayer
• Basic first-person shooter
  • Basic controls
  • Health powerup
  • Adding a melee weapon
  • Zombie-type enemies
  • Adding a gun
  • Soldier-type enemies
  • Adding a rocket launcher (explosions on bullet impact)
  • Adding a grenade launcher (same thing, with mass on the projectile and a timed explosion)
  • Adding a scoped rifle
  • Ragdolls physics
  • Multiplayer
• RPG
  • Basic controls
  • Magic / health powerups
  • Inventory system
  • Adding a melee weapon
  • Zombie-type enemies
  • Adding a crossbow
  • Crossbow with flaming bolts
  • Soldier-type enemies
  • Adding a magic spell
  • Ragdolls physics
  • Multiplayer

These are going to be heavy on programming, primarily Lua. I think what Roblox proves is that beginners can handle coding if it is presented the right way.

[yurembo_]

This is great! I think users need many different tutorials to develop games in different genres.

[WazMeister]

Magic and 100% way forward.

 

[OneHitWonder]

The 3 tiers of documentation
 

Tier 1: API Documentation

This is your raw, technical reference—method names, parameters, return types, etc. Think of it as the dictionary of the engine. It’s not meant to teach, but it is essential when you already know what you're doing and need specifics fast. Developers use this as their go-to for low-level details. Autogenerated docs from comments can live here, but they still need clarity and consistency to be useful.

Tier 2: Feature Documentation

This is where the “how” and “why” live. You describe how systems work (e.g., animation system, physics, input handling), what features are available, and common patterns or gotchas. These docs serve as bridges between the raw API and practical usage. Tutorials, conceptual overviews, and usage examples belong here. Great for onboarding new developers or understanding unfamiliar systems.

Tier 3: Project-Level or Implementation Docs

These are specific to the actual game(s) or tools being built with the engine. Think of them as internal guides: custom integrations, architectural decisions, version-specific quirks, or workflows followed. These can be end to end projects that cover many of the features described in more detail in Tier 2.
 

[Josh]

23 hours ago, OneHitWonder said:

Tier 2: Feature Documentation

This is where the “how” and “why” live. You describe how systems work (e.g., animation system, physics, input handling), what features are available, and common patterns or gotchas. These docs serve as bridges between the raw API and practical usage. Tutorials, conceptual overviews, and usage examples belong here. Great for onboarding new developers or understanding unfamiliar systems.

Should this include code or is it purely based on the editor? What are all the topics needed to be covered?

[yurembo_]

1 hour ago, Josh said:

Should this include code or is it purely based on the editor? What are all the topics needed to be covered?

I think you should explain these things together: the editor and the lua code and how to wide features with a help of C++.

[OneHitWonder]

4 hours ago, Josh said:

Should this include code or is it purely based on the editor? What are all the topics needed to be covered?

I believe it's important to reinforce the feature with a simple example and leave the complexity to tier 3, but I would say both but the theory is what is important here. 

Since I've been away from UltraEngine for a while, I wouldn't feel comfortable listing the topics to cover but definitely all the main systems and features Ultra Engine covers.