search

UPBGE / UPBGE-Docs

UPBGE Manual
https://upbge.org/docs/latest/manual/index.html
19 stars 16 forks source link

Documentation structure proposal #1

Open joelgomes1994 opened 6 years ago

joelgomes1994 commented 6 years ago

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. :smile:

UnidayStudio commented 6 years ago

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. :)

panzergame commented 6 years ago

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 :)

joelgomes1994 commented 6 years ago

@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 commented 6 years ago

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 commented 6 years ago

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. :smile:

panzergame commented 6 years ago

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 commented 6 years ago

@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 commented 6 years ago

@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 commented 6 years ago

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

joelgomes1994 commented 4 years ago

@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 commented 4 years ago

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 commented 4 years ago

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

lordloki commented 4 years ago

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)

lordloki commented 4 years ago

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). Therefore, as long as we do not reach a good level I will leave the API independently.

Once reached we can see ways to join both documents.

youle31 commented 4 years ago

Thanks very much for your works on documentation!

pepsi112-dude commented 4 years ago

The documentation is horrible, I cannot describe it.

Let's start shall we. ImageToArray, you do not offer examples with it, you just say some stuff and that is it.

Parameters: image – Image source object of type: VideoFFmpeg ImageFFmpeg ImageBuff ImageMirror ImageMix ImageRender ImageViewport

How do we convert array to image, to other things, how do we get pixels from it and so on. In stead you just said ImageToArray and near it "figure it out"

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 ? But how there is no example, It just says load buffer from image, there is no explenation about it. I had to search on other sites until my eyes popped out until I found something, I found that you can specify the source, to load to source such as imagebuff so you can replace the initiated buffer from texture.imagebuff, it gave me an error that with and height size do not match and I have not found anything regarding this neither on blender docs nor on the internet search engines. I just copied the error from the console and got zero results.

Error says buffer hasn't the correct size. and there is no refrence on anything where to search

This is even more disturbing: image Image data. (readonly)

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 :-1:

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, There is no way to export images for data manipulation with bge api, like render.render write=1 function bpy has. Only I think the screen shot function that takes just a screenshot of the whole screen.

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.

ShaunKulesa commented 4 years ago

@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.

lordloki commented 4 years ago

Yeah, we know that the documentation lack a lot examples. We are trying to improve it but we have limited resources. Regarding the other issues, for 0.2.5 it is not possible to use (and it never will) bpy for standalone. If you want to use it you will have to use 0.3 Alpha. Also, no new development effor will be put in 0.2.5 branch after 0.2.5b release (scheduled before year ends).

pepsi112-dude commented 4 years ago

Yeah, we know that the documentation lack a lot examples. We are trying to improve it but we have limited resources. Regarding the other issues, for 0.2.5 it is not possible to use (and it never will) bpy for standalone. If you want to use it you will have to use 0.3 Alpha. Also, no new development effor will be put in 0.2.5 branch after 0.2.5b release (scheduled before year ends).

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

pepsi112-dude commented 4 years ago

@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.

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.

ShaunKulesa commented 4 years ago

@pepsi112-dude https://discord.gg/Db8DjnYS

pepsi112-dude commented 4 years ago

@pepsi112-dude https://discord.gg/Db8DjnYS

Thanks Shaun, I will check this out

rcampos0 commented 3 years ago

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

rpaladin commented 2 years ago

Hi @joelgomes1994. Are you still interested helping with documentation? Currently images are still on legacy versions and not current.

Additionally, many of the links in your first post are outdated.

aum7 commented 9 months ago

i would like to know the purpose of : UPBGE-Docs / drafts folder

where should i move files from :