Documentation structure proposal #1
Comments
|
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:
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. :) |
|
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:
Thank you a lot for your work :) |
|
@UnidayStudio @panzergame 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. |
|
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! |
|
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. 😄 |
|
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 : 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. |
|
@panzergame Thanks for the answer. |
|
@joelgomes1994 I think that this structure can be enough to start the project. Good work!!! :-) P.D. I included a new "About this Manual" chapter. |
|
@lordloki WOW! I never saw this book before. What an amazing book! |
|
@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)? |
|
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). |
|
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 |
|
Just a remark. At this moment, I'm moving content from Mike pan book but i'm not adapting the content. I want to have all the content moved first and adapt this content after (rewording, new images, etc) |
|
Just for info about state:
I like more the initial proposal to have both manual & api in a unique document but it is less work to have them independent (I can almost automate the process). Once reached we can see ways to join both documents. |
|
Thanks very much for your works on documentation! |
|
The documentation is horrible, I cannot describe it. Let's start shall we.
and a few other words, no tuts, how it connects to other things, how to take the array further and convert it to an image maybe, or save data to file from it. I searched for this array on google, I came up with a few pages and they are vague. There is no tutorials on it how to use it in blender none. Upbge documentation has a few lines for it, this is not how a manual looks like. Let's take from bge.texture class stuff like load, image placed there out of contex with no syntax attached to them. load(imageBuffer, width, height), but how ? Error says buffer hasn't the correct size. and there is no refrence on anything where to search This is even more disturbing: Is it a plane, a rocket or superman, maybe it's a UFO because we don't know how to use it in context of a scripted line where this image is formulated like what Image= Magical mushrooms ? how do you use it , in what contex, with what. Syntax please. The results lack on google also because the lack of API refrence from blender game engine, the Bge documentation is the most "not there" on google. There are no tutorials, no real reffrence and example with sytax code. only Blender artists site where you have to beg for answers 👎 The documentation at least on bge module is mechanic, we are not robots. There are also basic functions that lack, when you run game engine in stand alone the BPY is gone, It would be nice to save image format from bge game engine from camera view, Bpy is not availible in stand alone mode, it's not part of the bge engine. These images could be used for data manipulation. I bashed my head trying to find it, my guess is that this non BPY function does not exist to render an image out of a camera and save it in some folder so we can load it back and make arrays out of it on the spot as game is running. |
|
@pepsi112-dude , doing the docs is time consuming. Commenting on your "Examples" complaint, at the bottom of most pages it says examples. If you want some examples on there if you have any spare time you could make some and one of us will add them. |
|
Yeah, we know that the documentation lack a lot examples. We are trying to improve it but we have limited resources. |
I have alpha 3, I was talking about 2.5 in the way that all the blender posts from the forum reagarding blender game engine is from that era. Most of them anyway, and few others more recent. I took a script from 2.5 and modified it, it's the rendertotexture script, beautiful projection with videotexture why it would be a shame not to be able to use blender.texture class and save images from it. It's all I could find on the internet 2.5 scripts regarding blender.texture render to texture |
Do you think I have enough expiriance to write blender api code, I'm just a beginer in blender's api, it's consuming but so it is frustrating for others who search for a start on upbge manual, who want to give blender game engine a chance. |
|
Thanks Shaun, I will check this out |
|
hello, everyone, a while ago, the group discussion, and the group quote about the Game Engine Book, I went to the repository, and forked the repository, for my github account. In order to translate it into Brazilian Portuguese, and start contributing something I can. you could take a look, a review has not been done, I’m just translated, there’s a little more to go until the end. https://github.com/rcampos0/GameEngineBook |
|
Hi @joelgomes1994. Additionally, many of the links in your first post are outdated. |
|
i would like to know the purpose of : where should i move files from :
|
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
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. 😄
The text was updated successfully, but these errors were encountered: