Tutorial Talk

[JohnK]

They "feel" like they have plenty of potential. Am going to be working on a system to make writing such PBT simpler (only about 1% simpler though, would still involve cloning a repository, using VSCode and Node). I did try writing the code directly into the playground but when testing found that code I had hidden was so well hidden I couldn't find it and had to start again and was up to #20 before I had a proper working example.  Another possibility would be to write the code in an editor such as Notepad++ and then copying it into a PG testing it with Run not Save and then back to Notepad++ and repeat. In the end going to the bother of having a working local playground proved much more efficient. So by simpler I just mean a few functions you can call on to make decorating/hiding lines less onerous.

This may take a while.

[Wingnut]

Oh man, you hid your own code and couldn't get it to show again?  aww... that sucks.  Drop us the URL, and perhaps @Jaskar, @Haylan and/or @Temechon... can rescue it.  I've seen them do some miracles.  Perhaps they can find your code-hider line(s) and remove them.

There's no way to iterate thru all the PG code lines, and un-hide them all, perhaps inside a function wrapped in a scene.executeWhenReady()?

Would that work?  I dunno.  I haven't had enough morning coffee, yet.  Perhaps you need a "load-but-don't-run" option, eh? 

Thanks for the info/feelings, J.

[Wingnut]

Who was it?  Dad72?  Someone mentioned that it was time we had a REALLY hand-holdy introduction/tutorial... for shaders.

Shaders are one of the most-difficult things to teach.  Ironically, Fluent-style programming is also difficult to teach, seemingly.

And thus... ShaderBuilder, is double-difficult.  But still, ShaderBuilder is a NICE "assemble shader piece-by-piece" wrapper... that also needs teaching.

Back to PBT's (playground-based tutorials).  I dunno.  I didn't have a point to make. 

I'm just thinking... perhaps there needs to be separate learning-flows: 

One branch... is an introduction to ShaderBuilder, including using IT to teach an intro to Fluent.  It ends with using shaderBuilder (with its Fluent coding style) to build a few shaders.

The other branch... using shaderStore... keeping shader-code in-playground, no talk of Fluent, and concentrate totally on how to write shader code, and how it works at the GPU level (diagrams, diagrams, diagrams, a serious use of Babylon GUI). 

Could use modeling, too... not just for showing results of new shaderMaterial, but also for teaching.  We're talking about some new animation funcs... mesh.spin, spinTo, move, moveTo... over in another thread area.  They could come-in useful... for moving mesh around in animation sequences... used as teaching aids.  *shrug*  Thinkin. 

Aside: I wonder if the playground could be made with multi-lingual options for ITS GUI.  String bundles?  Do folks still use those? 

[Wingnut]

Uh oh, I'm doing more demented thinking.  Subject... Scene Object Guided Tour - playground-based tutorial (PBT).  (Don't confuse-with PBR - Pabst Blue Ribbon beer).

In some earlier demented experiments, I tried some in-playground object inspecting... trying to gather all the property and method names... from an object such as the current scene object.

Limited success, I guess.  I borrowed the object inspector code from web.  Test PG is here - it is trying to gather Object.keys which have "observ" in their name.  Did pretty good.

But, I was thinking... we have intelli-sense in the PG... which means... something already has a list of methods and properties for current "scene".  Perhaps it even knows about over-loads... where user has created an extra property or method on current scene object.

The thought I have... is just a big 3D box... with Scene written on it.  Click it, and it "unfolds"... into Scene City... and then we go flying it's "neighborhoods", allowing users to stop their helicopter, click-on method-buildings and various city "properties".  (drill the scene object).  Then further clicking could give pop-up panels telling current values, and/or small info about what each method is used-for.

All part of the new "Drill/Tour Any JS Object In 3D" system.  Yum.   hmm.    We're shooting for... ahem... 7 year old and above, if possible.  Must be fun (+ power-learning).  Animate animate animate.  (spinTo, moveTo, scaleTo, ahem)    Tooti-frooti colors, too. 

Thinkin'.  Can a PBT access the intellisense DB?  hmm.  Perhaps, better to "glean" method names and property names (and values)... FROM the object itself, only when needed? 

Later, I think it SHOULD be allowed for user to switch to ANOTHER JS object... while mid-tour of a different object.  (jump to another target, such as camera).

Visual tours of objects... dynamically generated JS object 3D "view".  (model/view/controller).  3D tree view... but we'll start with drill-to-unfold boxes... and move to tree limbs later. 

[Wingnut]

Hi kids.  Over in another thread, there was some talk about teaching everyone... the terminology used in BabylonJS.  You know, what do all those fancy words MEAN/DO?

Are these things also called... a "glossary"?  I dunno, I'm no librarian. 

If we start a new Projects thread or something, we could start collecting lists of many words, and perhaps their definitions. 

IF we do that, there is another area I would like people to explore.  I want to locate all occurrences... of 2+ words.... that have the same definition. 

Ideally, we want to decide on ONE of them, and then eliminate all occurrences of THE OTHER word(s)... from our docs and class files.

Eventually, I would LOVE to make our docs... have clickable links to the definitions of certain words.  Perhaps, any word seen in ANY of our docs... which has a light blue background... is clickable, so reader can learn it's meaning.  Wouldn't that be sweet?!  Thoughts? (thx)

[kurhlaa]

16 hours ago, Wingnut said:

If we start a new Projects thread or something, we could start collecting lists of many words, and perhaps their definitions. 

Couldn't https://doc.babylonjs.com be filled with that? It already (or potentially will) contain all the possible objects, but is rather empty now. I believe that official documentation is the first place where people search for a detailed explanations

[Wingnut]

Yep... good idea.  Yeah, I was only going to use a forum thread... to solicit / collect all the terms that folks thought should be included in the glossary.  It's a place/way that lets people suggest words that they think should 'make the list'.  The thread topic might be "Suggestions for Glossary-Included Terms".

Then later... we make the actual glossary... somewhere within the docs section, as you suggest. 

When we get the actual glossary launched, folks can forever add-to/edit it, using current docs-editing methods.

Sorry for my poor clarity about the Projects thread - a bubbling / brain-storming thread.  It's an attempt at fair decision-by-committee and democracy in our commune-ity.

(Brain-storming should never be confused-with barn-storming, which is much more dangerous, physically). 

Fair decision-by-commitee (DBC) ... voting/consensus... is really slow sometimes. Sometimes, folks don't have time to study the issues/ramifications of a decision, and sometimes BJS users don't log-in often enough to stay informed about the evolving issue. 

It CAN require 6 months of discussion and voting... JUST to define what a "consensus" IS.  (I was once admin/wizard on moos, muds, and mushes... which are e-communes, when power-trippy arch-wizards aren't involved.)  

DBC is very hard work.  Gruesome, yet it's still the most fair way.  But, decisions like "Should we all step aside to avoid this charging rhino?"...those type of things need decisions that happen a bit faster.    

[Wingnut]

Well that subject certainly spurred a firestorm of interest.  heh.

Who needs a project?  In my recent docs touring, I realized that we really haven't got a good how-to doc... about basic textures.  We have docs about 20 different kinds of "special" textures, but no comprehensive all-in-one big boomer. 

What would it teach?  *shrug*

uWrap+, vOffset+, coordModes, addressMode, base64img, lower left corner origin, what are mipmaps, where's the invertY (the reason I went looking for texture docs, recently), CORS issues, and whatever else anyone can think-up.  Perhaps "touch-upon" what UVs are, and how they work.  (and perhaps what happens to a texture that is mapped-onto a mesh that has no UVs set).

My suggestion would be to avoid teaching material channels in THAT doc.  BUT, I think the doc should also contain links to info for dynamicTextures, and also a link to that cool "What textures are available in our playground" doc that somebody created (it rocks!). 

DynamicTextures and advanced context2d... really needs an entire doc to itself, especially if intending to "cover" most of context2d's power.  This doc could also cross-link with Creating Custom GUI Widgets... which could also use advanced context2d ops, I suspect.  Anyway, back onto subject...

The old "advanced texturing" doc... is/was... pretty scatter-shot, but a potential nice starting place.  I'm not sure what a "Basic Textures" doc should contain/cover. 

In a way, textures are not even on-subject for a 3D framework, eh?   Perhaps OUR Textures tutorial would only teach new BABYLON.Texture(params) and then perhaps... uAng/wrapV/uOffset stuff.

Anyway, let's give some thought to what a "Basic Textures" doc MIGHT look-like, and if/not we already have it covered with another doc.  A search for 'mipmap' really should return a link to a doc... that covers the use of mipmaps param in the BABYLON.Texture constructor, I would think.  To me, it seems there is a "hole" in our docs... regarding basic texture usage.  But, perhaps I am imagining it.    Thoughts welcome, as always.

[JohnK]

http://doc.babylonjs.com/resources/playground_textures

Can also find via http://doc.babylonjs.com/resources/documentation_category_map#P

Sorry Wingy misunderstood, you meant the doc you were talking about not the docs as a whole.

 

[Wingnut]

No probs...  its good, John.  You showed us the URL to that doc.  It's a good doc... helpful, bigtime.  It would be nice to 'table-ize' it, somehow.  *shrug*

Temechon once said that html inside of .md files... is honored during the docs build.  Sooooo... I dunno.  HTML table within the .md?  Scary.  Gotta style it somehow, too.

Let's farm-out some within-an-md html table testing... to one of the youngsters.    I know that the docs team LOVES getting hourly "please build the docs" requests.  heh.

You got docs-build powers/authority, @JohnK?  I dunno how it's done...  some kind of magic button, I suppose. 

I suppose... we COULD make that table... available as a choice in the playground gui.  (show 'local textures' page as popup window - choice, much like the floated debug panel).  This might dictate... that the ONLY html that we put in the .md doc... is an <iframe>.  That iframe pulls-in tableOfTextures.htm.  *shrug*  

GitHub markdown DOES have some of its own simple table stuff... but... it's pretty stiff and annoying.    And, if we use a markdown-based table, we can never make it also be a popup window in the PG app.  If the table is HTML, we keep the popup-in-PG option open, I think.
 

ANYway... the real subject of THIS post... is to talk about http://doc.babylonjs.com/how_to/observables

That list of Available Observables is out-of-date, right?

This morning, I went looking for engine.onResizeObservable and... you know, no mention of it in 'Available Observables' list.  Understandable.  The list of observables was bound to expand faster than docs maintenance.

Remember this playground?  https://www.babylonjs-playground.com/#1BTGPV#10

That's the goofy test PG... where I went "live-drilling" for property names... containing 'observ'.  I queried the scene, the engine, the sphere, and the light.  Scroll-down thru the list, as wanted.

We all see where I'm going with this, right?  Perhaps spruce-up my playground, make it much more powerful for finding observables (if possible), and then use a link in that doc... to that playground.   ie. Instead of a static list, we provide the user with a on-the-fly gleaned/gathered (dynamic) list of 'Available Observables'. 

Can it be done?  Thoughts?  Stupid idea?  Should we query/drill the PG's intellisense database instead?  hmm. 

Aside:  Today, I used the first ever engine.onResizeObservable in a playground scene.  I'm SO proud.    It's workin' goooood (drag divider between canvas and editor... while watching console.)  GUI positioning work happening - lines 1914-1965 area (yawn).  Trying to keep label rects ALWAYS X-positioned at about 20% of canvas.width.

[JohnK]

21 hours ago, Wingnut said:

It would be nice to 'table-ize' it, somehow

Have put the information into tables, lot of empty space but don't know how to remove it ! The power to deploy remains (as it should) with DK but the power to edit is given to all. So it might be a day or so before you can view the result.

[Wingnut]

Thx J!  You used .md tables, John?  Yeah, they are "white-spacey".

You should put a little HTML table at the bottom of the doc... just for a test... see if it blows-up the build.   heh. 

You have a home-build ready to go, I bet. You could check if HTML is allowed by the build, right there at the house, I suppose.    (wear safety gear, eh?)

Maybe put some embedded style and other attributes in the tags...  ie.  <table width="95%" style="border: 4pt inset firebrick">

I bet we can trash the build.  I dunno if anyone has ever tried embedded HTML, but maybe. 

There IS a tiny bit of html embedded in our MD right now....

https://github.com/BabylonJS/Documentation/edit/master/content/resources/Reference/offsite_tutorials_list.md

Lines 9, 33, 48, etc.  It is a special HTML tag that causes MD tables to be WIDE WIDE WIDE (after they're built into HTML).    Cool, huh?  I think Temechon installed that for me... to silence my narrow-tables whining.    The Off-Site Tutorials List has nice wide tables. 

The underscores on each side of __Title__ header... was an attempt to force column 0 to be wider... which would prevent word-wrapping in column 0.  It has failed, but it was a good attempt.  Currently, the column widths have NO controls at all, as far as we can tell.  Column0 appears to be about 15%, col1 = 25%, col2 = 65%.  Nobody knows WHY.  heh.  Strange.  Docs-build Gremlins, I guess. 

But I'm curious if an HTML table is allowed inside our MD files.  Perhaps a bad idea, but still, it would be good to know.    Thx again for your hard work, JK!  You're a savior.

[JohnK]

From what I have read you can have HTML tags im markdown just to lazy to to do the table.

 

[Wingnut]

Oh, me too, definitely.  That's why we farm it out to the kids. 

Do you think it will handle a <script> element?

http://webpages.charter.net/wingthing/html/tablehell04.htm

View source.  Just an empty table element near the bottom, a huge array of data, and some thundering table-building JS.  Even the styling is done dynamically.

Mainly, just two elements... a script element and a table element.  Curious? 

If we can crash a build... using ONLY a piece of .md content... then we get our "Docs-Build Crashers" certificate and shoulder patch!  heh

[JohnK]

No <script> for markdown but just for fun here is part of your table as a png file after saving it from the browser as a pdf file, using an online converter to change the pdf file to an HTML file extracting the <table>...</table> from that file, pasting the <table.  </table> into a md file and building the md file into an html file and viewing it in the browser and using the 'snippet' app to take a picture so I can show you the result of doing all this.

 

Have to go and lie down now . Decided I will leave the PG textures doc as it is!

[Wingnut]

[Wingnut hugs JK]  Thx for the tests, JK!  Well done.

See, IF we could have used <script>... THEN... it is conceivable that we could query the textures folder (only when someone browsed the list - JIT - just in time), and "glean" or "derive" the table... using the current folder contents of /textures.  (On-the-fly table-building).  Any future additions to the textures folder... would auto-magically be reflected in the generated dynamic table.  (sorry for the over-explain, but there are more readers than you and I).

I was hoping for the same thing... with the list of observables/observers.  If we could dynamically glean the list of 'observ' terms... from the PG intellisense DB (or from querying something else)... then the list of observers/ables... would NEVER go out-of-date/stale.

*sigh*  oh well.  It was a good "piping" dream.    thx agn... get well soon. 

[Wingnut]

Hi guys.

    What happened to the current list of observers/observables?   Didn't it used-to-be at http://doc.babylonjs.com/how_to/observables ?

Anyone know?  Thx.

[JohnK]

Yes there was a list it was the one below. Tomorrow I will track down when it disappeared and why.

* scene.onDisposeObservable
* scene.onBeforeRenderObservable
* scene.onAfterRenderObservable
* scene.onReadyObservable
* scene.onBeforeCameraRenderObservable
* scene.onAfterCameraRenderObservable
* scene.onNewCameraAddedObservable
* scene.onCameraRemovedObservable
* scene.onNewLightAddedObservable
* scene.onLightRemovedObservable
* scene.onNewGeometryAddedObservable
* scene.onGeometryRemovedObservable
* scene.onNewMeshAddedObservable
* scene.onMeshRemovedObservable
* scene.onPrePointerObservable
* scene.onPointerObservable
* layer.onDisposeObservable
* layer.onBeforeRenderObservable
* layer.onAfterRenderObservable
* material.onDisposeObservable
* material.onBindObservable
* baseTexture.onDisposeObservable
* renderTargetTexture.onAfterUnbindObservable
* renderTargetTexture.onBeforeRenderObservable
* renderTargetTexture.onAfterRenderObservable
* renderTargetTexture.onClearObservable
* abstractMesh.onDisposeObservable
* abstractMesh.onCollideObservable
* abstractMesh.onCollisionPositionChangeObservable
* abstractMesh.onAfterWorldMatrixUpdateObservable
* mesh.onBeforeRenderObservable
* mesh.onAfterRenderObservable
* mesh.onBeforeDrawObservable
* particleSystem.onDisposeObservable
* postProcess.onActivateObservable
* postProcess.onSizeChangedObservable
* postProcess.onApplyObservable
* postProcess.onBeforeRenderObservable
* postProcess.onAfterRenderObservable.
* spriteManager.onDisposeObservable

 

[Guest]

I removed it as it was no more accurate at all (we introduced many more observables)

[Pryme8]

Where can I get more info on making a Playground Based Tutorial?

[Guest]

pinging its mastermind @JohnK

[JohnK]

@Pryme8 if you have already read these

http://doc.babylonjs.com/resources/hiding_editor_lines

http://doc.babylonjs.com/resources/pbt_slider

http://doc.babylonjs.com/resources/pbt_writing

http://doc.babylonjs.com/resources/pbt_previous_and_next

Then you will need to ask me a specific question but please do not expect a quick response as I am a little busy at the present. Will have more time from Tuesday next week.

[Wingnut]

http://doc.babylonjs.com/api.html

Gettin' kind-of pretty.  Somebody is doing some serious work. 

I wonder... if telling @JohnK that our docs build allows HTML... was a dangerous thing to do. 

What an endeavor! 

Soon, can we right-click on a property or method, auth-in with our curator password, and easily edit the 'info', which then automatically submits a PR behind the scenes?  hehe.  erf. 

I once talked about that 'quick edit with a web form' potential feature... on a private "Docs" thread... with the docs team.  Easy Edits... 1.0.    On the PR-approver side of things... mega-workload and potentially serious discussion/bickering about wording/length of the property or method info.

I think, for example... basic info for scene.ambientColor... is stored INSIDE OF scene.ts... the actual source-code file for Scene Class.

This means... there is a serious potential for over-teaching a property or method... which will make scene.ts become a big fat pig, perhaps 4 times its current file size.

What I once proposed... was a separate 'more info' database/file... but the guys convinced me that it would be a point of "decision-by-committee-to-death", and a maintenance nightmare.

They're right.  Yeah, we ALL want "show us some demo usages and playgrounds that use scene.ambientColor"...  handy clickables near the property name in the API "class docs".  But... that requires that "secondary layer"... which cannot be automated and would require continuous human nurse-maiding and updating. 

Really, automating is the only way.

Each 'info' included with each property or method in a .ts file... will probably need to be kept small and succinct, but we can surely include a couple of clickable icons.  Click to search forum for this method/property, click to search standard docs, or search playground in-code, playground tags, web, with/without class name included (ie. 'scene.ambientColor' or just 'ambientColor').

These handy clickables/icons... can be generated automatically, during the build.  These links might promote brevity/succinctness in the .ts files, and will CERTAINLY be of high benefit to properties and methods which have NO info, currently.

Just some thoughts.  Be well, gang.

[JohnK]

On 3/26/2018 at 2:31 PM, Wingnut said:

I wonder... if telling @JohnK that our docs build allows HTML... was a dangerous thing to do. 

Cannot take the credit for this, if only I was skilled enough.

 

On 3/26/2018 at 2:31 PM, Wingnut said:

This means... there is a serious potential for over-teaching a property or method... which will make scene.ts become a big fat pig, perhaps 4 times its current file size.

If 'big fat pig` files ever become an issue then perhaps there could be distributed files that have the comments in the source files stripped out. Possible or wise I do not know.

Keep on challenging

Coming up in the next docs deployment is "how to contribute to the API documentation" but it is certainly far from click, add some text, submit. Volunteers still needed.

EDIT Now available http://doc.babylonjs.com/how_to/contribute_to_api

[Wingnut]

Hi kids.

http://doc.babylonjs.com/how_to/gui

Me thinks that colorpicker is NOT a container.  It is a control.  @adam may wish to comment or be the one to adjust the docs.

If nobody disagrees or adjusts the doc after some time, I will adjust.

Also, after study, I think "Line spacing" and Resize to Fit" should be deeper into TOC hierarchy  (...if possible.  One more # prefix for each header?)   Both should be subs/children of TextBlock, I suspect. 

"spacing" could be capitalized. 

Thoughts?  Thx.