Documentation structure proposal

[joelgomes1994]

Hello! Here I show my proposal on the documentation structure, I'm already working at it, but I'm publishing it to enable a discussion if it's really a good planning, or can be enhanced.

The latest development build of this manual can be viewed here.

UPBGE Directed Manual

First, the documentation is a merge of Blender manual (Game Engine section only) and UPBGE's Python API (UPBGE and Standalone modules only).

The manual will only contain UPBGE's specific features or, at most, game dev specific tasks, and any generic definition will have a link to the related subject on the Blender official manual. For example, the manual may explain the game specific definitions on materials, but for general materials settings the manual will provide a link to Blender official manual, on the Materials section.

From now on, I will refer only to Blender manual pages inside Game Engine section.

Rework of Manual Tree Structure

The document's structure on official Blender manual is somewhat messy, with no contexts or sub themes, along with some pages that don't belong in there. My proposal is to make a context based manual:

MANUAL

• Introduction - This chapter is totally adapted to UPBGE 0.3
  • Briefing
  • A Deeper Look
  • Compatibility Notes
• Tutorials
  • Getting Started
    • 3D Basic Concepts
    • Game Basic Concepts
    • Blender/UPBGE Basics
  • Introducing Logic Bricks
    • Moving A Cube
    • First person camera
    • Playing An Animation
    • Using Linked Libraries In Game
  • Introducing Logic Nodes - This chapter is totally adapted to UPBGE 0.3
    • A First Example
  • Introducing Python Scripting
    • Basic Concepts
    • Moving A Cube
    • Playing An Animation
    • Dealing With Group Instances
  • Introducing Python Components
    • Setting Up A Python Component
• Editors
  • Properties Editor
    • Render
    • Scene
    • World
    • Object
    • Constraints
    • Texture
    • Physics
    • Materials
    • Data
  • Logic Bricks Editor
    • Logic Bricks Area
    • Properties Panel
    • Components Panel
  • Logic Nodes Editor
    • Properties Panel
    • Logic Nodes Area
  • Python Editor
    • Properties Panel
    • Python Area
• Logic Bricks - This chapter is totally adapted to UPBGE 0.3
  • Introduction
  • Sensors
  • Controllers
  • Actuators
  • Properties
  • States
• Logic Nodes
  • Getting Started
    • Creating A Basic Logic Tree
    • Creating A Character
  • Node types
    • Condition Nodes
    • Parameter Nodes
    • Action Nodes
• Python Scripting
  • Introduction
  • Python And The Game Engine
  • Understanding Inheritance And Composition In Game Scripting
• Python Components - This chapter is totally adapted to UPBGE 0.3
  • Introduction
  • Getting Started
    • Character Controller Templates
    • Top Down Templates
    • Vehicle Templates
    • Util Templates
• Physics
  • Introduction
  • World Settings
  • Object Settings
    • No collision
    • Static
    • Dynamic
    • Rigid body
    • Soft body
    • Character
    • Navigation
    • Common Settings
  • Material Settings
  • Constraints
  • Sensors
  • Vehicle Physics
  • Other Tips
• Release Game
  • Licensing of Games
  • Performance Considerations
  • Standalone Player
  • Release Procedure
• Tools
  • API Stubs
• About This Manual - This chapter is totally adapted to UPBGE 0.3
  • Introduction to the UPBGE Manual
    • Conventions
    • Contribute
  • Manual License and Credits
  • What's New

Note that some important topics aren't listed on the proposal (like Camera, World, Physics), it is because those topics will be part of Editors > Properties Editor, according to its subject (Camera in Data tab, World in World tab, and so on). Also, I thought about moving the Logic top section to Editors > Logic Editor's subsection, but it will depend on the upcoming logic nodes (Node Editor will be added to Editors).

I'll be waiting for enhancement comments on this proposal, thanks. 😄

[UnidayStudio]

I loved the idea. It's very complete now. This initiative will attract lots of new users.

My suggestion, however, is to add a section on the beggining that guide the new users into their first "game" (not a game, just something beautiful moving on the screen). This will increse the retention of the game engine to new users. Because if in some short period of time, the new user creates something unique, the chances are that they will be less likely to abandon the software.

Something like the "Getting Started" tab in other game engines:

• Unreal Engine: https://docs.unrealengine.com/en-US/GettingStarted
• Unity: https://docs.unity3d.com/560/Documentation/Manual/GettingStarted.html
• Armory: https://armory3d.org/manual/#/

This section don't need to be complex. Just a shortcut to ensure that the new users will stay with us for a while. We can also create links between the getting started stuff and the real documentation stuff, like: "Un this area you can control the lamp settings, wich you can have a deep explanation later on, or by clicking here link".

I can write this section, if you guys want. :)

[panzergame]

Fantastic work ! Nice reorganization, indeed the previous documentation was not really maintained and even less reorganized.

About exposing mostly the difference from BFBGE and UPBGE you can link to this page https://doc.upbge.org/api-changes.php.

I agree with @UnidayStudio about adding quick example, i have a short list of them:

• move a cube with a key fully from logic bricks
• move a cube from python script
• play an animation from brick
• play an animation from python
• add an object from brick
• add an object from python
• setup a python component

Thank you a lot for your work :)

[joelgomes1994]

@UnidayStudio @panzergame
Thanks you both for the feedback, I just added a section called 'Tutorials' on the proposal top post, and 'getting started' tutorials will be inserted on them.

There will be a 'Basic Concepts' chapter on each tutorial, explaining concepts like 'pulses' (on logic bricks), the structure of Python classes and functions (on Python tutorial).

I will try to get some concepts from Monster's Guides on Blender Artists, his guides are brief and amazingly well made, I learned a lot from it on my early days of BGE.

[youle31]

Wow, big project :) Then if you and @lordloki want/accept to work on this project, maybe you could find a way to collaborate efficiently. Thanks for your work and involvment!

[joelgomes1994]

Hey guys, could you take a look in this page? It's somewhat the format I intend to continue writing the manual, exposing detailed info about UPBGE specific features, explaining Blender features focusing on UPBGE uses of these features while providing a link to Blender Manual for detailed info about these features. I want a feedback about what could be improved. Thanks. 😄

[panzergame]

The page is correct, and descriptions are concise. Also what about linking API reference (e.g object color) in the manual ? Just say me if it is interesting or not.

Some minor notes, for future rewrite :
In https://upbge-docs.readthedocs.io/en/latest/manual/editors/properties/materials.html, The alpha to coverage mode allows to do clip alpha but using multiple sample (it works only when multi-samples is enable) and make smooth edges.

Also the billboard mode is using the Z object axis and not the Z world axis as before, which allow you to do any kind of billboards.

[joelgomes1994]

@panzergame Thanks for the answer.
The API links is a good idea indeed, not only for object color, but for any value available in GUI and Python.
About the Materials tab page, I didn't touched it yet. I've added some checkmarks on the structure proposal above showing which articles are done, which ones are present but need to be reworked (as the Materials one, from Blender manual) and which ones must be written.

[lordloki]

@joelgomes1994 I think that this structure can be enough to start the project. Good work!!! :-)
Once it is over we can think to integrate information from https://github.com/mikepan/GameEngineBook
I have created a wiki page to include the proposed structure.

P.D. I included a new "About this Manual" chapter.

[UnidayStudio]

@lordloki WOW! I never saw this book before. What an amazing book!

[joelgomes1994]

@lordloki I see that you have commited to this repository recently. When I was editing the docs, when trying to include the bpy API reference, I discovered that Read The Docs was not able to build it due to the large ammount of pages and overall size of it. It says "timeout" when building and don't finish it, needing the paid version of RTD. I don't know if you'll experience this issue, but is a migration to another domain viable (maybe Github Pages or something alike)?

[lordloki]

Yes, i rented weeks ago another server to update upbge.org webpage but i didn't have time to wake up yet. When is up we can add the bpy pages (i think that there is a limit of 400000 files).

[lordloki]

I've just updated the structure proposal. The new parts added we can fill them with Mike Pan game engine book and with @IzaZed Logic nodes documentation