Documentation feedback wanted - What would you like to see improved?

[yaustar]

We are looking to improve our documentation and really want to focus on areas that have affected our community the most. We would love to hear your feedback about using the documentation and tutorials so we can do our best to act on it!

Topics include (but not limited to):

• What are we missing that turned into hours long search on the forums?
• What do you need that is not available yet?
• How easy/hard is it to find the information that you need?
• What are your common use cases for projects
• What would be your ideal/dream documentation site/flow?
• Are the tutorial samples enough?
• How do you go about looking for information?

Looking forward to hearing your feedback !

[LeXXik]

Perhaps, I could share my experience with Playcanvas, even though I am still learning it.

The very first steps for me were to go through the User Manual and afer that checking all Tutorials. Most of the tutorials are just projects, demonstrating a feature of the engine. I didn’t go through the code, but simply looked what was possible with it. Later, when I started my first project and had a need to implement a feature, I was like “Oh, I think there was some example that showed something similar to it”. I would then go through the tutorials again and try to find it.

Probably the most informational and valuable from the learning perspective for me was the Keepy Up tutorial series. It introduced me with most of the important basic concepts of the engine and how to use them. After completing it, I was able to create my own game. I think it would be nice, if there would be more tutorials like that. The good thing about the series is that they not only show how to use a feature (like in most of the examples currently), but also can explain why it is used this way or another.

My dream documentation would be the one, which doesn’t require me to look anywhere else for the information. For example, at some point I was learning how to use Firebase and its services. When the time came to do the developement, I rarely googled the questions I had - all the info is easily available through their documention guides and videos.

Playcanvas has a forum with an amazing community to support most of the questions during the beginning of the learning path. I’ve learned a lot from asking here (still can’t think of a way to properly thank Leonidas for every bit of wisdom he shared). After learning something new, for example, batching or object pooling, that I am not familiar with, I would then google and try to read as much as I can about the topic. Then I returned here, read the guide to see how the engine does it and try to use in my own project.

The thing is though, I have read that guide about batching guide before. But since I had no previous experience in developing games (or 3d graphics in general), I had no notion of what it means and whether I really need it. So, when the time came, I didn’t even remember about it, until I was pointed to it. Probably, some tutorial series could be added where perfomance topics would be covered.

In the more recent times, I am fighting with the index and vertex buffers. Even though I am already familiar with the concept, e.g. what they are and why they are needed, I still don’t have a clear understanding on the graphics pipeline of the engine. For example, it is hard for me to take a standard WebGL code of drawing a primitive and map it to the engine calls that I am required to execute in order to do the same thing. There is a vertex buffer iterator, but do I actually need it to iterate through the buffer indexes, and what happens if I don’t lock the buffer before doing so, or why would I need to lock it in the first place. Similar questions to these are not really explained in the guides and most of the time I spend reading the engine source code.

[Christina]

I would like to share my experience with Playcanvas too.

I started learning Playcanvas approximately 3 years ago. When I opened the User Manual for the first time most of the stuff were making sense, given that I was coming from Unity and everything seemed quite familiar. But when the time for coding came and I opened the tutorials, I felt a bit overwhelmed by the fact that, most of the tutorials were just a Playcanvas project. Which was great in a sense that, I had the chance to study how someone would organize the hierarchy, the codebase etc. I have to say I wasn’t a JS expert at that time so I was struggling with that too, so walking through another’s person’s codebase was really really hard. And to be honest I just closed the page and left.

But, driven by the idea of developing games and 3D content on the web and share them very easily without having to install anything or compile any code, I came back pretty quickly.

Some things I would love to see in the documentation:

Some beginner level tutorials teaching Playcanva’s API and why not, some Javascript? That would attract people that they won’t have to know Javascript.

Some tutorials on 3D maths and the most common concepts in Game Development. (priceless!)

Some advance tutorials like shaders and GLSL or even performance optimization

I could propose ideas until tomorrow but my point is, that the goal of the Documentation could be to help people with no Game Development experience to easily getting started and feel welcoming in Playcanvas.

An example I can share is Godot’s Documentation: https://docs.godotengine.org/en/stable/

[Albertos]

In general I find the documentation very neat.

Personally, I am not an intensive user of the documentation. Sometimes I use it when I receive a link from someone. When I go to the documentation to be able to give feedback I immediately notice that almost all my points of attention are about the terms used.

Is the documentation different from the user manual? Or is it the same thing? In that case I like to see a “Manual” button instead of a “Docs” button. When I click on the button I get on a page “PlayCanvas Developer Resources”. Is that the same as “Documentation”?

Personally really like the tuturials. I’m looking for the tutorial that matches and then I use it as an example for my own project. I would remove the extra “Editor” button to avoid confusion and duplicate tabs. I also would rename the “Tutorials” to “Examples”. Then you can create a separate section for actual tutorials to follow.

In addition to the tutorials, I regularly visit an API Reference. Here I really miss enough explanation and examples. Sometimes I just end up on a page with only title headings.

Furthermore, I would like to see a little more contrast between the different parts on a particular page. For example, give all examples in use an orange background tint.

[plasmalasgun]

Working with others people Unity scripts is about the same experience, granted there is much more of middleware/modules available in the asset store or what you can ‘creatively’ lift from others unity git repos; however your ability to interpret others code to do what you want is often more useful than the ability of taking someone else predigested code from some tutorial…

[yaustar]

Thank you everyone for the feedback, it really means a lot to receive such detailed replies.

I will collate ideas going forward into a GitHub issue on the documentation site sometime this week for more detailed review and feedback.

@LeXXik

The thing is though, I have read that guide about batching guide before. But since I had no previous experience in developing games (or 3d graphics in general), I had no notion of what it means and whether I really need it.

@Christina

Some tutorials on 3D maths and the most common concepts in Game Development. (priceless!)

This brings up a more general point that was commented on by @Thomas_Due_Nielsen in another thread about concepts that we use such as batching, variable scoping for callbacks, etc that we don’t really explain or point to other resources to learn more.

Definitely something we need to add.

@Christina

But when the time for coding came and I opened the tutorials, I felt a bit overwhelmed by the fact that, most of the tutorials were just a Playcanvas project.

We definitely need some way to split the two.

@Albertos

I also would rename the “Tutorials” to “Examples”. Then you can create a separate section for actual tutorials to follow.

@Albertos

In addition to the tutorials, I regularly visit an API Reference. Here I really miss enough explanation and examples.

We are thinking about adding more thorough information and mini examples in the API docs. In some areas they are a bit thin.

@Albertos

Sometimes I just end up on a page with only title headings.

That is too thin If you see them again, can you post a bug about them either on the forums or the GitHub page please? https://github.com/playcanvas/developer.playcanvas.com/issues

@Christina

Some advance tutorials like shaders and GLSL or even performance optimization

Shaders and GLSL will be given a little boost as we are working on a system to make making shaders a lot easier at the moment. Noted that we should extend our optimization section too.

[KpoKec]

Documentation is often not detailed enough (like raycastresult detail in raycastall).
Sometimes there is not enough link to github with a class (like rigidbody layers and trigger research).
Sometimes description wrapped by using others naming (like material vs standartmaterial - where description with difference?).
May be create special topic with docs edit request?
Code examples in docs are good and do not cause additional questions ))

[yaustar]

Thanks @KpoKec!

@KpoKec

May be create special topic with docs edit request?

If it’s to do with the API, please post feedback on the engine repo as that’s generated by JS docs.

playcanvas/engine

Tutorials and the user manual feedback would be in this repo https://github.com/playcanvas/developer.playcanvas.com/issues

@KpoKec

like material vs standartmaterial - where description with difference?

Good point, we should really make that more clear which one should be used.

[plasmalasgun]

I would like to have detailed tutorials on using shaders, even though basic rendering dont need them, and the chunks used by playcanvas are listed on git and well optimized, it should be good to have examples ranging from simple vertex transforms, listing the attributes and uniforms, point light, direction light, bumpmapping… only when the programmer understand how these correctly be implemented on playcanvas then he can reinterpret more complex shaders or translate them to the specific glsl version that playcanvas use in comparison to the other types of available code (Ex. Attributes and Varying are considered deprecated, in and out are to be used, transformation matrices are automatically generated and passed to the shader (VP, Light matrices…)

[yaustar]

We are currently working a node based material editor to make this a lot easier. I talk with the developers to see if we can provide more documentation without effectively doing it twice when the new system is published.

[plasmalasgun]

After learning some shaders… ive just realized that they cannot be batched and models that use them cannot be merged as different graphnodes into of a single model (without reverse enginering the batching system) , otherwise we would need a draw call per object and if the model is imported merged as a single fbx object, there is the possibility of bloatness because you need to pass in the entire model that is made of duplicate geometry… being able to merge these models would allow you to ‘fake batch’ your shaders and allow to transform each graphnode addressing them individually

[Leonidas]

@plasmalasgun you can take a look at hardware instancing if you would like finer control over each instance (translation/shading):

https://playcanvas.github.io/#graphics/hardware-instancing.html

Hardware instancing and color

Hi, I’m building a football stadium with thousands of moving plane primitives in the stands, that comprise a card stunt system. Each one will be coloured with a single colour, and will basically act like a pixel in an image, and when assembled together, they’ll recreate that image. I also want to be able to change the image, so in a “wave”, cards will gradually flip around and change to a new colour to reveal a new image within a second or two. I’m using hardware instancing, as explained here:…

[plasmalasgun]

So if I want to use hardware instance, and I have a single model with all the desired parts stored in unique graphnodes… lets call them ‘part0’, ‘part’, ‘part2’… would I need to create 3 mesh instances each with their own vertex buffers to store the matrices of the transformations of each of the parts(3 passes, 1 pass per part)…or should i just cram all parts into a single model and render it with one pass despite duplicate ‘parts’… thanks!

[yaustar]

Could you use batching instead?

[Leonidas]

Hi @plasmalasgun,

For hardware instancing you enable it once per mesh instance. So say you have a tree model with two mesh instances, one for the bark and one for the leaves. You will create two instances arrays, two vertex buffers and enable instancing on each mesh instances.

Check this example on how the code should be structured:

https://playcanvas.github.io/#graphics/hardware-instancing.html

[plasmalasgun]

Can you batch with custom shaders?

[lloydevans]

I came to PlayCanvas with an existing background of web/game development. Here are some thoughts from me:

When I first started using PlayCanvas, I would generally be searching the docs to find out how to create or modify what I’d just set up in the editor via script. I’d often find an editor docs page, but then have to dig around to find relevant API docs. Perhaps links to relevant API pages in the editor docs and possibly the editor itself would be nice.

Another thing I’d commonly be searching for is event names and how the event systems work. It seems the documentation on this has improved and the type definitions also help.

I think improvements on the code editor and ability to use es5+ JS would help beginners a lot. If you are starting out coding the last thing you want to worry about is browser support for JS. At this point a lot of learning resources and code libs/examples are es6 JS so that’s going to be a point of confusion for people new to it.

Improvements to type definitions would be nice. I’ve encountered a handful of missing and incorrect types which I need to create issues for.

The docs search function is basic but does the job. The forum via Google will often be a source of info too.

My dream in terms of scripting environment would be ability to use ES6 and TS in an editor much like stackblitz (monokai). This puts most of the docs you’d ever need to look up right in the editor. Until then I set things up in an offline code editor unless it’s very small scripts.

The examples are awesome and do a great job of inspiring and showing what playcanvas can do. It seems a lot of the demo code is set up using playcanvas engine only, which is nice in that it’s totally self contained, but also a little inconvenient that you get some boilerplate code not really necessary for the example.

[yaustar]

Thanks for the detailed feedback!

@lloydevans

When I first started using PlayCanvas, I would generally be searching the docs to find out how to create or modify what I’d just set up in the editor via script. I’d often find an editor docs page, but then have to dig around to find relevant API docs.

Can you give an example on what you were looking for and where your search had led you?

@lloydevans

Until then I set things up in an offline code editor unless it’s very small scripts.

Out of interest, are you using our playcanvas-sync tool on GitHub?

@lloydevans

It seems a lot of the demo code is set up using playcanvas engine only, which is nice in that it’s totally self contained, but also a little inconvenient that you get some boilerplate code not really necessary for the example.

Just to clarify, are you referring to the examples at playcanvas.github.io and would you like to see the same or similar examples via the PlayCanvas Editor?

[lloydevans]

Can you give an example on what you were looking for and where your search had led you?

Thinking back I wasn’t familiar with playcanvas and how it adds objects on entity like sound, element etc. or the addComponent method on entity. There wasn’t the detailed info on the string type passed to addComponent when I was looking.

Say I add add a sound component in editor, what I need to know is something like:

entity.addComonent("sound");
entity.sound.volume = 0.5;

And the API page SoundComponent | PlayCanvas API Reference

My search to getting these things will be on the API docs finding the Entity and SoundComponent pages.

Out of interest, are you using our playcanvas-sync tool on GitHub?

Yea I am using it and it makes setting up the offline editor quite easy which is great.

Just to clarify, are you referring to the examples at playcanvas.github.io and would you like to see the same or similar examples via the PlayCanvas Editor?

Yes, those are the ones. Possibly would be nice, yes. I don’t mind either way but might make them a little more readable and also help ensure they are up to date with latest engine.

[underlight]

From perspective of a seasoned PlayCanvas developer - the biggest drag for me is obscure and unfinalized Shader Chunk API. Advanced commercial projects usually require custom shaders and postprocessing - and even though the basic examples can be found in tutorials I still have to go through program lib / shader sources every time I want to make something custom.

Another thing - the source code itself could be improved in terms of readibility and comment / code ratio (I mean not counting JS docs which serve different purpose). For example - Lightmapper.bake is huge monolithic function completely obscure to anyone willing to customize / improve it. GraphicsDevice, ForwardRenderer would also greatly benefit from splitting functions into simpler ones and commenting a majority of non-obvious steps.

Cheers!