Tutorial Talk

[JohnK]

You are right of course. I took a programmatic view, keep the number of headings down for the top menu and because I am writing it pages go where I say they do. An overview should do just that give a brief overview of that object and all its features, babylon 101 the old playpen tutorials designed to be read in sequence,  a tutorial gives more detail whether it is a how to or not, export and import together, extensions generally not in core and throw in some examples and don't interfere with classes or playground.

If its acceptable and becomes the new docs and in the future someone does not like it and decides a re-write is much better then all well and good.

What I would really have liked to do but was just too much work was to have each method or property of a class on separate pages with descriptions of use and examples for each.

Never will keep everybody happy all the time.

Party on my friend

[Wingnut]

Yeah.  Actually, a tutorial gives less detail, in a way.  Often they are "step-by-step - how to activate this thing" and very little else. 

But, yes, more detail is put into the "delivery".  More verbally-described metaphors...  "it works somewhat like a frobnitz with a gizmo", etc.  Over-explaining, re-iterating, hand-holding, lots of code examples, PG links, fluffy fluffy fluffy... for the kids the old people.  hehe

Yeah, a programmer/organizer wants hierarchy and symmetrical structure.  But the human learning curve often wants stories and whimsy...  Benji's Adventure Trip to Babylonia.  Engaging magical stories of wizards and dragons and beautiful princesses who turn into toads when you lick them.    Learning SO GOOD, SO FUN, that it's sought.  Not easy.

Some want it succinct, and some want it woven into a tale, and some want about a 50/50 mix.

I guess wikipedia does it rather nicely.  In any given sentence about anything, there are links attached to the words used.  That is the "terminology" helper.  Terminology is a HUGE part of the learning curve to BJS and webGL.  HUGE.  Will our "docs by everyone" system ever be able to do that, or follow those documentation conventions?  Unlikely.  Besides, making links to every "webGL term" used throughout our docs system... would be a crap-load of work (if not automated).

There ALMOST seems to be a difference... between documenting the framework, and teaching it.  It almost needs two different kinds of docs...  INFO-side docs (no BS, down and dirty), and LEARNING-side (gentle, talkie, example-heavy, etc).   Yet, careful here.  Too much text... makes stuff "look" more difficult.  Size of doc can overwhelm at first glance, so... too much explaining can kill fun, too.  Balancing act.  Possible solve... playgrounds that show'n'tell.  Entire learning courses... in a single "chapter-sequenced" playground.  hmm.  In-playground text appears... "Okay, look at THIS section of the code..."  (a small block of code is highlighted in the editor window and scrolled to editor screen center).  "This is where we do the blah blah blah.  (Hit key to continue)".  You get the idea.

Worst of all, there's no good/bad, right/wrong answer to any of this stuff (but thinking about it long enough... WILL produce a nice brain tumor.)    We have some unique teaching tools here, and it causes us to have opportunities for unique teaching systems... never used before.  We're trailblazing!  Scary!

[JohnK]

4 minutes ago, Wingnut said:

There ALMOST seems to be a difference... between documenting the framework, and teaching it.  It almost needs two different kinds of docs...  INFO-side docs (no BS, down and dirty), and LEARNING-side (gentle, talkie, example-heavy, etc). 

Maybe this is a way to go. Always liked the idea of a reference and a guide and perhaps a separate section for other tools and resources. Maybe the landing page would give you a choice this way to a reference for short descriptions and examples and the api, this way to the story of how to do it with examples for larger tasks and this way for the editor or blender. 

Overviews mainly part of reference, Babylon 101 part of guide. 

Would also help sort out some of the comments DK had.

Certainly enough already in docs for reference and would be happy sorting that side out. Less sure about the guide side.

Got a big family weekend from tomorrow so give it more thought next week.

[JohnK]

Quote

officially, there are 7 ways to do it.  Which do we teach?  One side of me says "Wingnut, pick the way that you like the best, and keep it introductory"... but that's not fair to the reader/user. 

Another side of me... then says "Wingnut, you need to show all the ways, and tell of the advantages/disadvantages of each way.  Also tell of the cool properties and methods available to each way."

First of all you are right that this is the place for discussion.

The way I understand it now there will be two main sections

Features and How To

That there are 7 ways to label a mesh is a feature and there would be a page that describes the feature and how it is useful and list the ways to do it. Then there would be one or more How To pages that describes how to do each.

OK there is a long way to go before something with all this in happens.

Perhaps the How To pages would be story type pages and perhaps there is another set of pages technicals/details/structures/manuals (as you see I am still trying to find a good category title)

My wishful thinking is if it is possible to get the current pages into good and clear categories it will be easier to use and perhaps help others to write at least parts of the documentation they may feel happy with.

 

[Wingnut]

Good thinkin's. 

I just realized today how little I know about renderingGroups/ID's.  I need to study it and find/write a good tutorial on the subject.  DK reminded me of it, recently, when answering a forumer's question.  So, just ignore me, here... I'm making a self-reminder.    (also curious if anyone knows-of a good tut/PG on the subject - thx)

update: unh,  its all right here.  Duh, wingy. 

[Wingnut]

Hi guys.  Recently, I was touring this tutorial about rotation and translation,  and I saw a section that says this:

"The property rotation will be used if the property rotationQuaternion is null (default behavior)."

- I believe rotationQuaternion can be undefined, too.  Is null and undefined... the same thing?

"The property rotationQuaternion only is used if both are set."

- I'm not sure if that is true.

I did some testing.  https://www.babylonjs-playground.com/#0QL6BB#1

Line 16 sure makes our sphere go to hell, eh?  Line 17 works, though.

Line 15 is a standard rotation.  Activate it... and keep line 16 active, too.  No change.

Now de-activate line 16, but keep lines 15 and 17 active.  Line 17 is the boss, and it doesn't care if line 15 is active or not.

Deduction:  I don't think using Quaternion rotation NEEDS to have standard/Euler .rotation set, too.

Also, I question whether/not line 16 should affect mesh scaling/size, but it sure does.  Thoughts, anyone?  Thx.

[Pryme8]

not sure, but this fixes it sphere.rotationQuaternion = (new BABYLON.Quaternion(0, 1.5, .5, 0)).normalize();

[GameMonetize]

"The property rotationQuaternion only is used if both are set.": Not completely accurate. The real sentence should be: rotationQuaternion has priority

[Wingnut]

thx dk!

4 hours ago, Deltakosh said:

rotationQuaternion has priority...

...unless rotationQuaternion == BABYLON.Quaternion.Identity();   ?? 

https://www.babylonjs-playground.com/#0QL6BB#3

*shrug*    Line 30 working good.  But, activate line 17, NOP line 18,  then line 30 is no-go.    weird. 

Update:  Oh, I see.  When line 17 is sphere.rotationQuaternion = new BABYLON.Quaternion(0,0,0,1), then it acts the same as .Identity().  I had it set 0,0,0,0.

So, 0,0,0,1 is a "no-magnitude" Quat, and therefore THAT Quat is not a higher priority than .rotation.  hmm.  (like I know.)  (Wingy hands-out moist towelettes to those suffering from that "not-so-fresh" feeling.)

[GameMonetize]

Lol I had to open the code because I did not remember at all

But you are completely right

 

[Wingnut]

  Wow, Deltakosh didn't have answer from top-of-head!  That's rare. 

So, this is one of "those things".  Remember me saying that... at SOME point... a tutorial crosses from being "introductory" (just the basics)... into being "comprehensive" (every detail and ramification).  This is one of those "crossing points". 

I like using the "wishy-washy" non-sure-footed statement, then.

"Under most circumstances, the mesh.rotationQuaternion (when it has been defined)... has priority over mesh.rotation.

Could use "Generally-speaking", too.  Either method, we don't tell the reader that the OTHER CIRCUMSTANCE is when .rotationQuaternion == .Identity() or (0,0,0,1).  They don't need to know that. 

But by doing that, did our tutorial lose its "comprehensive" rating... from the International Tutorial Writer's Guild? 

So, we study document writing... years of post-graduate study on data presentation, and we carefully define the lines between "introductory" and "comprehensive".  Everything is perfect.  Paragraphs don't wander or go whimsical... yet the document is a joy to read, and user actually SEEKS reading it because it is as much entertainment as it is learning.

And then... some 7 year old grown-up wanna-be... asks... "Hey... why doesn't the docs tell us about Quat.Indentity NOT overriding .rotation?" 

We say... "Oh... ok... just to satisfy your whiny ass... feel free to add some text to the tutorial... regarding that."

Well sheeeooot... Sally SevenYearOld puts it in the wrong place in the doc, words it like it was written in Swahili, and "generally speaking"... just makes a mess of one of the tutorial paragraphs. Then, she saves the doc with 20 extra blank lines at the bottom.    She is SO PROUD that she has edited an "official tutorial" and become part of the Babylon JS Team... that you don't have the heart to clean-up her mess.  It might hurt her little 7 yr old feelings.  *sigh*

Is this called "strawman" stuff?  Imagining-up a scenario that might never happen?  *nod*  Ya'll KNOW what the easy and proper solve for this stuff is, right?  Yep, roto-tiller all 7 year olds... into your gardens.  Ooooh... Roto-Tiller-Killer... what a great scary movie idea!

Oh, I got off-topic.  Yep, WHAT IS telling too much (text overload) and WHAT IS telling too little... in a tutorial/overview?  hmm.  Probably BRANCHING is the wise move.  In intro docs... "If you want to know more about this, go here."   "More info about that, see this."...  etc.  Modular.  Keep the documents small, clean, but have MANY documents.  But this can clutter our "list of overviews" or "list of tutorials"... due to so many "little tuts" 

I dunno.  Why am I still talking?    I think I'll go run-over some 7-yr olds with my pickup... see if I feel better afterwards.    (jk, of course)

[Wingnut]

Hi gang!  New idea!!!  Well, older idea but thinking about moving forward on it.

http://doc.babylonjs.com/tutorials/position,_rotate,_translate_and_spaces

That is our excellent "PosRot" tutorial... which I THINK was written by Professor @JohnK, teacher extraordinaire.

This tutorial suffers from a lack of "watch it happen" stuff, imho.  Sooooooo...  I was thinking about using Babylon GUI and some kind of "Page System" ("click button to continue")...  to make an all-in-one-playground version of this tutorial.  I have talked-of playground-based tutorials before, but I have never seriously TRIED one.

So, I guess I need a system where text-display, and 3D scene... can live nicely together, and likely with a by-default hidden editor.

But WITH the editor hidden, maybe THAT AREA is where I do all the text displaying during this click-button-to-continue sequenced (paged) tutorial?  hmm.

If I want the webVR/headGear folk to be able to read/see the tutorial while wearing their headgear, I need to use Babylon GUI, and not HTML text, I think.

When wearing VR headgear, can folks see the playground editor area? 

Or is it ONLY the canvas area that is viewed? 

Or is that user-choose-able?   Hidden via PG's "hide editor" choice?

I have SO MUCH to learn.  It is not a problem to use all Babylon GUI for my text... except... HTML is still more powerful.  The editor area is currently HTML, and that means... animated gifs/pngs, video, full CSS/boxModels, scroll and overflow, mid-sentence color and font changing, there's a pile of power in HTML.

BUT... can VR folk SEE the editor area (if chosen-to)???  And if they CAN see it, how big do they need the fonts?

And then the BIG question... WHY would anyone wear a VR headset for half-screen of 3D, which == completely NON-immersive. 

I could put all the Babylon GUI on a plane, and then allow the viewee to position the text-displaying plane wherever they wish... closer, farther, left or right, etc.

Oh how I wish for HTML document-on-a-plane, but I don't foresee THAT happening anytime soon.

I'm also thinking about how to translate these text panels into other languages.  Ideas about that - let's hear 'em, please.  (thx)

All thoughts/comments/ideas... wholeheartedly welcomed.  Any answers to Wingnut's lack of knowledge about VR gear... quite welcomed, too.  thx!

[JohnK]

Like the "watch it happen" idea and a PG version would be great. Just to let you know that though the page you linked to will continue to exist as the guide will continue to exist I am still working on re-structuring the official documentation which I hope to finish soon and submit to DK for his approval. The development of this is online for checking but still a couple of issues or so. 

EDIT Documentation now update

To understand translate, rotate and spaces you will now need to read the following page

http://doc.babylonjs.com/How_To/Rotate

and perhaps these as well

http://doc.babylonjs.com/babylon101/Position

http://doc.babylonjs.com/features/Position,_Rotation,_Scaling

Cannot help you with VR but when I have finished with the documentation would be happy to help with an interactive tutorial. Go idea to start doing on a PG but perhaps it might be better hosted separate to the PG as a new repository on babylon.js github.

Looking forward to your first attempts.

[Wingnut]

Sounds good, John... thanks for all your hard work!  I won't get in the way of anything, I don't think.  Mostly, I need to ponder a "playground tutorial framework" (a toolbox).

Once upon a time, I talked about having enough control of the editor... to temporarily FLASH or colorize (or copy to GUI textBlocks) small sections of code... in/from the editor.

The playground-based tutorial's... BabGui text... might say... "We are about to activate THIS section of code". 

Then the editor actually scrolls-to THAT code line/block... and flashes it, or borders it... SOMETHING to show the tutorial viewee WHICH section of editor code... that the tutorial is speaking-of.

In Firefox (with Firebug?)... I can highlight a line of code in the editor, right click to see context menu, and choose "inspect element".  This opens the HTML inspector in Firefox's F12 dev tools area.  There, I can "see" the structure of the editor's html doc that contains the inspected element.

Many of the code lines... are in multiple pieces, spans within spans within spans.  Back in the old days, I could EASILY concat their textContent in the proper code-line.  These days, my brain gets foggy.  Also, I hear a distant voice yelling "recurse it!"

https://www.babylonjs-playground.com/#PVA5YC#4

Watch console.  (and use your 'inspect element' to launch your doc inspector, if you have one). 

I am having SOME success at console, but I have some kind of problem in my nested for-loops... lines 33-36.  (I just heard that voice again... "recursion, dude!")  I need these code-lines to output to console perfectly.  THEN I know I can get good copies of each line... for use in GUI textBlocks, as needed.  Very handy for "Teaching With The Playground".  Or... "Using BJS to Teach BJS"  

If someone would like to clean up my crap, that would be fine.  Later, likely, I will ONLY be setting the style on the parent of a code line... often a simple color change or some bordering.  Just something to gain user eye-focus ... just before the "click GO button to see it happen"... is started.

I already got some yellow CSS text colors in an earlier test, but then I accidentally mis-used a WHILE-loop, and my browser went mesmerized. 

I'd almost say... that the editor codeNodes... are not "in-order".  They seem to follow ANY order within the HtmlNodeCollection (such as childNodes), and are only "sequenced" via their CSS style.top value.  How weird, if that is the case.  If this is true, I will need a lineNumberToCssTopValue(lineNumber)... in order to properly absolutely-position my borders.  ERF!  What a way to obfuscate PG code... set all codeNodes.style.top = "10%".  All code lines would Y-position atop each other... in the editor.  Pretty difficult to read (but users could still zip'n'snarf),  Fun.  Could easily vibrate all the codeNodes up and down real fast, making them difficult to read (earth quake).  heh

Ahh, HtmlNodeCollections and playground practical jokes... gotta love 'em. 

Thx for any help/work.  I'll probably need a scrollEditorToLine(lineNumber)... soon, too, if anyone is SUPER-energetic.  Oh wait, that might be scrollEditor(yValueInPixels).  hehe.  I'm not sure that we can count-on line numbers AT ALL.    I'm scared! 

Out-of-order codeNodes... could explain my messy nested for-loop output.  hmm.

Off-topic Extra:  Is anyone annoyed-by the PG editor 'minimap' view?  document.getElementsByClassName('minimap')[0].style.display = "none";   It's gone.    Change "none" to "block"... to re-activate it.  In the olden days of other languages... we could do:

 if (var t = document.getElementsByClassName('minimap')[0].style.display) { t = "none" };

That line would automatically check if we were in playground... where a node of class minimap existed, and if true, don't display it.  But, I don't think ECMAscript allows assigning temp variables within an IF statement.  To do it with JS/ES, I think the line needs to be a bit longer.

IF a user downloaded a playground ZIP with THAT line of code within it... it would return false/noAction... because that node doesn't exist... when not RUN in a playground.   SOME experts might say... "Thoust shalst NOT reference the editor, from code STORED WITHIN that editor."   

But, we have special needs for THIS project, right?  Our guru suggests... "You must become one with the editor, grasshopper".

[JohnK]

On 10/20/2017 at 5:15 PM, Wingnut said:

This tutorial suffers from a lack of "watch it happen" stuff, imho.  Sooooooo...  I was thinking about using Babylon GUI and some kind of "Page System" ("click button to continue")...  to make an all-in-one-playground version of this tutorial.  I have talked-of playground-based tutorials before, but I have never seriously TRIED one.

 

On 10/20/2017 at 5:34 PM, JohnK said:

Cannot help you with VR but when I have finished with the documentation would be happy to help with an interactive tutorial. Go idea to start doing on a PG but perhaps it might be better hosted separate to the PG as a new repository on babylon.js github.

Gave it a go which you probably already know, as you're not slow and got my ping from the section demo

[Wingnut]

You're a friggin' genius, John!  Sooooo nice!  I got demo-drool ALL OVER my keyboard. 

[JohnK]

If you want to design and plot out another PBT then we can give it a go.

[Wingnut]

Thx.  I'll think on it.

As you likely know, over in TWC, I have been whining about harvesting code-lines from the editor (rough).

I was hoping that, someday, $editor would be a core-ified constant in playground environment.  THEN... we could do things like...

$editor.showLines(nnn, nnn) and $editor.hideLines(same)... and $editor.colorLines()... etc.  These "special playgrounds" with the hidden PBT-driver code... would need to carry some PBT/$editor data WITH THEM, stored in their Azure DB record.

Anyway, you get the drift.  I can certainly understand why you decided to disallow user-editing, so far.

A scene-scoped "eval-me:" text field might be fun... in PBT's.  This would allow the users to send commands to scene items... yet not insert anything into the editor code.  The tutorial could even "suggest" eval-line-text into the text field FOR THE USER, and say "Hit the RUN-IT button when you are done staring-at/adjusting-on the Eval-Line" 

Almost like... type-in your own button event.  Up/down arrows when text field is focused... scroll thru back-buffer of previous evals, or similar.   Nice. 

[JohnK]

Mmmmm I think this should be possible (or something close to it). So I do not only partially understand is there any chance of a sketched out design of where buttons and dialogue boxes might be placed. Also what would be really helpful would be a rough walkthrough of an example say for the basic scene PG showing this is where: suggestions are given; lines need to be hidden; lines shown; "eval-me" text field used and how and scrolling though.

If there is a possibility of doing this no rush as I know you are busy with you physics landing module thingy.

 

[Wingnut]

Well, that's darned kind of you to ask... but I really had no game-plan.  I have been thinking about "is this possible?" and you certainly ended my thinking about that.  It is VERY possible and Johnny-K DID IT... beautifully.  The only reason I want to hide lines... was to make the code that created the tutorial... be hidden in the talked-about scene code (help avoid users getting confused about the massive amount of PBT-driver-code which makes the tutorial HAPPEN).

This thinking... was all done back-when I thought the tutorial code (what I call pbt-driver code)... needed to be contained-within the actual playground that is being taught.

I don't exactly know HOW you are doing it... but it doesn't matter... cuz you did it, and it works great!  Now I am most interested-in...Can ANYONE make one, using ONLY the playground app?  It is really not so important that I make PBT.  It is important to provide a mechanism, so that if ANYONE needs to "talk someone through" some playground code... we have a tool to allow/facilitate it.  Where GUI is located, how presented, what can be included, etc, etc... perhaps is best left-to the PBT authors. 

In my opinion, even your little test demo PBT... added MUCH clarity to that position/rotate/translate text-tutorial.  You NAILED "watch it happen" PERFECTLY.  Right now... I'm VERY excited about what you have accomplished... but I haven't quite come-to-grips with its full potential for the future.

Also, I have a "pipe dream"... of allowing the text used in PBT's... to be translated.    Tough goal, but I don't want to give-up on it.

Perhaps, now is a time to solicit ideas... from others (oh yeah, that's what you have now done). 

You have built the first demo PBT and it is NICE.  It opened the "what is possible" door... WIDELY.  I guess, current objective might be teaching us how you did it.  Right now, you have a "thing" that "looks like" a playground, but actually isn't one.  IS there an actual playground that has the exact same code?  A link to that... from your "thing"... might be cool.

Actually, I suppose you have created a sPBT... simulated-playground-based tutorial. 

I guess first... I would need to learn exactly how your new PBT system... works.  Then I might be able to speak more-intelligently. 

How about a "jump BACK one step" option in PBT's?  Or how about "run last step backwards until arriving at previous step"?  Wow!  Cooooool! 

[Wingnut]

Ya know, I think... when Deltakosh created...

BABYLON.Animation.CreateAndStartAnimation('boxscale', box1, 'scaling.x', 30, 120, 1.0, 1.5);

...is wasn't "taken" quite far-enough towards Easyville.  It seems we could still use mesh/light.spinTo(), .moveTo(), and .scaleTo()... automatic animators.  (None would work on cams, and scaleTo would not work on lights)

I think it was @JCPalmer that created abstract mesh's POV stuff... which are only for mesh, of course.   I'm not sure what is the purpose for those "point of view" features, but... they seem interesting.  They are not animation creators, though.

With spinTo(), .moveTo(), and .scaleTo(), folks will (someday soon) want to make them more powerful... allowing easing, speeds, loop/pingpong cycle options, etc.  Those extra features COULD be facilitated with an optional {options} parameter, I suppose.  But the objective here...  is MORE simplicity for simple animations.  I think this would make our PBT's easier/faster to code.

Just thinkin'.   Surely a dangerous activity on my part. 

[JCPalmer]

@Wingnut, I really cannot jump into a thread on the 12th page easily.  Not sure what this has to do with tutorials either.

Will say that  POV movement & rotation is at the Node level for the QI extension, not just mesh.  See these scenes (you have probably before) where the camera is going thru a series of POV move / rotations, 1 & 2.

We touched on this topic before, though.  Somewhere else, I asked to promote POV methods up to Node, but because of differences in implementation that idea got rejected.  Another option might be to just implement separate functions of the same name at the light & camera levels.

Still not sure what this is about, and these are not animation creators for sure, but values out of calcMovePOV, & calcRotatePOV could be supplied to position or rotation animations.

[Wingnut]

*nod*.  I meant to type your name, not ping you, JC.  Sorry.  You were accidentally included in my "looking for super-easy animation methods"... for animated tutorials written in playgrounds.

Thx for the info about POV.  Upper-level "overload" funcs... definitely a good idea. 

POV probably won't be useful for our project, but I appreciate the visit/info.

It's simple to add .spinTo(), moveTo(), and scaleTo()... to mesh class (inside a test playground).  They would just be EZ-use wrappers for CreateAndStartAnimation().

Not important.  Wingnut just rattling-on. 

[JohnK]

The following two PBT examples are written wholly within the existing PG editor in the browser.

https://www.babylonjs-playground.com/#N3PAT

https://www.babylonjs-playground.com/#XDSW52#12

Editing is not permitted in either but it could be allowed, just need to work out how to adjust the editor hiding and showing of correct lines if users do some editing.

Am I getting closer to what you are imagining?

[Wingnut]

Oh absolutely!  Yeah, I thought about that "moving target" with the line numbers.... if editing allowed.

Man, you got this editor MASTERED!  Very very cool!  Yeah, editing is likely ONLY a tutorial-author/maintainer thing.  No real need for average user to do it.

Interesting!!!  Wow... these are some BIG breakthroughs.  This system "feels" powerful to me.  Feels like we doubled our teaching power/tools (vs. a text/pics tut).

How do they "feel" to you, J?  (and big-time thx for your work/research on these things.  I think they are marvelous!)