Tutorial Talk

[Wingnut]

Hi gang!

 

Here begins the never-ending thread... about babylon.js tutorials.  Post freely in here - about any tutorial.

 

Here in the early days of this thread, I would like us to talk mostly about 'the basic series' of tutorials:

 

https://github.com/BabylonJS/Babylon.js/wiki/Tutorials

 

We will need input from everyone.  We will be doing test translations.  We will be collecting pictures that are perfect for the tutorials.  We will be collecting great ideas and always looking for ways to make things clear for all.  Comment freely.

 

Here are some early things that we are wanting your comments about:

 

----------

#1: The use of 'arg' and 'arguments'.  ie. function(arg, arg, arg, arg).  Early tutorials called them 'parameters'.  In tutorial #6, I started using 'arg' and args. Does anyone think that 'arg', 'args', 'arguments', etc... is outdated or wrong?  Is ECMA officially calling them parameters?  Should we avoid calling them args and get back to 'parameters'?  Thoughts?  Comments?
----------
#2: The use of the term 'one-line constructor' (see tutorial 6).  Here, we used 'constructor' to define a one-line Babylon scene item maker such as var light0 = new BABYLON.HemisphericLight("Hemi0", new BABYLON.Vector3(0, 1, 0), scene);  Does anyone think that 'constructor' is a bad term to use for that 'line'? 

 

For babylon.js, that single line scene item maker is not only a constructor... but also an 'installer', yes?  In other frameworks, you first 'construct' (make) a scene item, and then you need to do scene.add(item).  Babylon.js does the add for the user.  Comments welcome... about 'constructor'.
----------

 

Hey, thanks, everyone!  We will be watching this thread forever.  No hurry on commenting, and feel free to change your minds and comments later.  A special thanks to Dad72 for recently showing me that light.isEnabled PROPERTY... has been changed to .isEnabled() ... a getter FUNCTION.  And that the new way to change a scene item 'enabled'... is with .setEnabled() function.  His information not only fixed a section at the top of the #6 lights tutorial, but it fixed some personal projects as well.  Thanks again, Dad72.

 

camera_or_light_or_mesh.setEnabled(1 or 0);   ... that is the way.   But don't forget about light.intensity and scene.setActiveCamera[by](something) and mesh.visibility and StandardMaterial.alpha.  All are good ways to think about... when you want to make things appear and disappear.  Do not trust my typing.  Be sure to visit http://doc.babylonjs.com to find the perfect syntax.

 

The #6 lights tutorial is still being edited.  I (Wingnut) hope to clarify the .direction property somewhat.  Tutorial #5 about cameras... is scheduled for some work, soon.  Feel free to comment about those things, or about anything in the GitHub tutorials.  We are listening carefully.  Be well!

[GameMonetize]

Honestly I like this tutorial (the last part is really great) but if you don't mind could you:

- Remove CAPS

- Remove the IDEA part. This is not useful here

- use babylon.js and not BabylonJS

- do not use too "american specific" expression like meats'and potatoes  (or 'topsy-turvy' or any slang word )

[Wingnut]

Can do.  Thanks DK!  I will wait a little while, though (if you don't mind), and hear more comments.  For example, the idea section will go, but what do we do in lieu of that?  Try to make a really nice light demo to link-to at the bottom... a place where users can experiment with all the light-types in one easy demo? 

 

Deltakosh, and other users... please comment on that as well.  "What to do now that the 'idea' section is leaving" 

 

How about underlining?  Avoid that too?  Maybe I don't even have that option in github markdown.  *shrug* how about bolding?  I need some way to put some expressive power behind certain words... and italics is already being used for property names.

[GameMonetize]

The tutorial itself is the experiment for me

 

Underlining is ok and you can do that with MD:)

[Wingnut]

Hi, thx for the comment.

 

If the tutorial itself is the experiment, then why is there a lights features test on the Babylon.js website?  It even uses animation (deja vu?) to help users watch how lights work with materials.  Yet if a user wants their own working copy of that demo to use as an experimentation jig, its like pulling teeth to get that demo as a stand-alone or zip. 

 

Because the Babylon.js website uses an odd html-swapping system, the user can't even use 'view source' to get a copy of that light demo in that way, either.  They don't even get to look at the source code for the lights demo.  If they want a copy, they have to dig it out of the github folders and download it from there.  Then, they need to pray that it runs on their home system and doesn't run into the XHR security wall.  (unlikely for the lights demo, but common for any demo using .babylon files.).

 

I am just telling you what happened to me, and is still happening.  There are few stand-alone demos to test-with and experiment-with basic features.  That's why I started making my own basic demos and tests, and releasing them as click-to-runs and zips on the forum.

 

Dk, you have a really fine "keep it simple" attitude... but not when it comes to the design of the BJS website.  That is far from simple.  A new user cannot view the source of any of the BJS demos or feature tests... because of the dynamic html-swapping main webpage.

 

Look at the easily source-viewable and easily zip-downloadable demos/tests on The Wingnut Chronicles.  Some use scenes divided into separate JS files, some use the 'go' global object, some are all-in-the-html, a little bit of everything. 

 

So, I am going to stand-strong with my opinion that a lights playground is still needed, and then a cameras playground will be needed as well.  I will work on them when I can, and provide links to them in the forum... if links to lights/cameras playgrounds cannot be put at the bottom of the tutorials.

 

I am sorry that my counter-comment was so 'heavy'.  People are probably starting to fear giving their opinions. hehe.  My emotions and fire... show that I care, eh?  I do.  I believe in BJS.  It is a real nice piece of work!  I want to see it explode in popularity.

 

PS: An easy "orbit-anything" device would be handy for cameras and lights playgrounds, yes?  Even Wingnut has a method to his madness, but its usually foggy and riddled with mistakes.

[GameMonetize]

I can understand that going to https://github.com/BabylonJS/Babylon.js/tree/master/Samples/Scenes/Customs can be hard to find

 

So in this case why not just linking the demo code in the tutorial ?

For instance for lights it could be:

https://github.com/BabylonJS/Babylon.js/blob/master/Samples/Scenes/Customs/lights_test.js

[Wingnut]

That's not bad, dk, but its not a click-and-run or an unzip-and-go.  That function needs to be 'inserted' into a scene template, but the user has seen the basic scene template many times by now/then.  Yet, it still needs to be inserted... and that takes the 'simple' out of it.  *shrug*

 

But yeah, definitely a wise link to put at the bottom of a lights tutorial.  You bet.  One of many links? 

 

PS: I love that sin and cos stuff in the animations section down there.  YUM!  That is the 'stuff' of orbiting!  I failed that part of high school. 

[GameMonetize]

So do you mind if I ask you to update the tutorial accordingly?

[Wingnut]

ok.  I will get it done in a few hours.  I was hoping to gather a few more opinions, first, but it looks like our friends don't have many opinions to express about tutorial 6.  I will get it done, real soon.

 

I will also adjust all the other items that you wanted adjusted, and install a link to the aforementioned url.

 

Take care.

[Wingnut]

Ok, all done.  As always, I began editing the current version (not a local-saved version), so all the edits I did just now... included all of dk's edits from yesterday.  DK, I hope I didn't trample any edits that you have made.  Adjust at will, of course.  I will be proofreading for awhile, myself. 

 

I do not really like the way I used to "deliver" the link to the github lights demo function.  I needed to talk them through the procedure to install the function.... at least somewhat.  NOT simple for the user... involved highlight and pasting and the raw button and and and... sigh.  grrrrr.  (Wingy shakes his head at the lack of simple).

 

Look over that section carefully... adjust at will.  I'll watch for a couple days, and we can all talk here.  I did a tiny bit of adjusting around the intensity and setEnabled section at the top.  Other than those two things, I just implemented the requests in post #2 of this thread.  I might have missed some... but I will still not edit for at least two days.... give us some time to look and talk.

 

I do not see underlining as a legal md tool.  No button on my home editor, and no button on the github editor.  Also no mention of it in a few 'github-flavored markdown' documents I quick-browsed.  I'll search more.  But for now, no expressive words in tutorial 6.  Its ok.  :/  We will figure out something.

[GameMonetize]

From my point of view this is pretty neat

 

Thanks a lot for your help

[Wingnut]

My pleasure.  I just finished tweaking tutorials 1-3, too.  Ballsy of me, huh?  All very minor things... but leave them all alone, cuz they're done right.  hehe.  Someday we might talk about the word 'tuto', though.  (sounds African)   Nothing can be done about that now, because of the zipped sources.

 

The most ballsy thing I did... was in tutorial 3... in this line

 

"Now you know how to create and move objects in a scene, but all your meshes have the same 'skin'! Not for long if you read the next tutorial about materials and textures"

 

Previously, it was something like... 'they all have the same looks'.  Well no they don't.  They are different primitives... so they don't look the same in that huge way. 

 

They have the same 'material' or 'surface' or 'skin'... or something like that.  Any of those three terms is fine with me, but not 'look'.

 

Also, it WAS ...  'next tutorial about textures'.  Is a color... considered a type of texture?

 

Maybe that line should be...  'next tutorial about colors and textures'

 

Or maybe... 'next tutorial about materials'

 

Your call.  But I don't think it should be JUST textures... UNLESS... color is a type of texture.

 

Meticulous SOB I am, huh?  You wouldn't want a tutorial adjuster any other way, right? 

 

Might as well change the name of this thread... to be 'Tutorial Talk'... if you will be so kind.  We'll use this place to do just that... talk about tutorials.  Sound good?

 

If you change the name of the thread, see if you can remove the tag 'lights', too... if ya want.

 

Someday we can talk about my over-use of elipses ( ... ) and under-use of commas, and my sentences that go on and on and on and on and on... and then on some more, and even more. 

[GameMonetize]

I do not think that colors are textured

 

And thank you very much for your help. This is definitely useful (and because you are american you can help me speak a better english!)

 

PS: "next tutorial about materials" sounds good

[Wingnut]

Actually, we Americans speak terrible English.  heh.  And then Wingnut adds a second layer of terrible. 

 

Titles... use caps in their significant words.  ie. The HTML Part, The Javascript Part, Create a Basic Scene, Object Collisions, Collisions by Gravity.  Est-ce bien avec vous? 

[GameMonetize]

Yes it is:)

[Wingnut]

Hi deltakosh and everyone else!  I recently learned much about light.direction.  I would like to add a small section to the lights tutorial... to teach what I have learned.  I would like to add Extra Information about Light.direction. 

 

Is tutorial 6 getting too big?  If not, where should I add it?  It would be most-appropriate to be added just after the picture for Directional Light.  But it could be put at the bottom, too, either before or after the other 'extra information' section.  Thoughts?  Thanks!  I think the addition will be about 8 lines.  Less lines IS possible, but I would like to introduce some easy methods... like showing the user that they can use the same numbers of a mesh.position ... as the numbers to put into spotlight.direction.  Example:

 

spotlight.direction = mesh_to_light_up.position;   (I love the 'simple' of that!)

 

Also, somehow, I would like to tell about lights not being able to shine on back faces.  I'm not quite sure how to do that... but... I think that would be 2-3 lines.  We can talk about that later, after I have learned more about that.

[GameMonetize]

AFAIC I would say right after the Directional Light stuff

 

And if you explain stuff for back faces do not forget to mention why (normals)

[Wingnut]

Boy, http://blogs.msdn.com/b/eternalcoding/archive/2013/07/01/babylon-js-unleash-the-standardmaterial-for-your-babylon-js-game.aspx is pretty nice.  Better than the GitHub Tutorial #4, maybe.

 

Basic Series, Advanced Series, I am having some difficulty seeing which is what.    What was the purpose of the MSDN blog posts?  Fresher than the GitHub tutorials?  Should I convert / merge the above URL... to be Tutorial #4 in GitHub markdown?  Thoughts?

 

Also, maybe, it is time to say goodbye to 'download the zipped source here'  (in most tutorials). 

 

It seems there are about 4 ways to 'make a basic scene'.

 

#1. The 5-file system.  With lots of separate JS  ie. main_tuto.js, scene_tuto.js, etc.  My offline tutorial http://urbanproductions.com/wingy/babylon/tutorial/master.htm calls them babylonprep.js and myscene.js, but the zipped source still uses main_tuto and scene_tuto... which are names that I don't really like (sorry).  All in all, that is a 5-file system.  babylon.js, hand.js, main.js, scene.js, and something.htm.  Main.js could be called startup.js, too, maybe.

 

#2. The 3-file system.  babylon.js, hand.js, and an html page... NOT using a window.onload event to start code.

          (inside body element, or after body element)

 

#3. The 3-file system.  babylon.js, hand.js, and an html page... IS using window.onload event to start code.

          (inside body element, or after body element)

 

#4.  A mix of the above 3 ways.... such as #2 and #3 code start... but still using main.js and scene.js.

 

Scoping is involved in all that.  I'm not very smart about scope.  I sometimes use a 'go' object... a global object... to help in my scoping problems.  Some say that is dangerous, and poor programming. 

 

*shrug*  Sometimes I think... offer them only one zip... which gives them one basic scene... in all 4 basic scene methods.  I don't know.  I am trying to make things easier... trying to avoid remaking source zips for the tutorials. 

 

Give them a single zip... here's everything you ever need to know about making a very basic scene.zip

 

Then, never offer any zipped source for any tutorial beyond that.  Just teach them everything they need to know about the 4 ways... in tutorial #1 and #2 (Basic scene and Basic Elements).  Offer them a zipped source in those two tutorials, and then never offer zipped source again.  Easier maintenance.

 

Just thinking.  Thoughts?  Too much in one post, eh?  nod.

[Temechon]

I think if there is one zip file to give a newbie is the #1 with 5 files. I feel it is better to start a project this way, with a good separation between the view (HTML) and the model/controler (JS).

 

IMO, all solutions with the javascript directly in the HTML file should not be done.

 

But that's just my opinion

[Wingnut]

Thanks for the comment.  Yeah, the 5-file system is good, for the reasons you have stated.  There is some drawback. Its when deltakosh or other helpers ask "Can you send me a small example of the problem you are having?"  And even for sharing little learned things friend-to-friend, 5-file can be more difficult.  I am not sure if those are worthwhile concerns, though.

 

I was actually thinking of that one zip maybe containing examples of all ways, and maybe even a document or two in there, teaching why/when the 5-file system is good, and why/when other methods could be used. The babylon.js starter kit. 

 

Maybe... the term/phenomena of 'abstraction' gets involved here.  I had a friend who tried to teach me about abstraction in the past.  I don't think I was a very good student.  I think I went over-abstraction crazy for awhile when I did a project in REXX.  It was a basic text adventure game and I think I had 52 subroutines in separate files.  It became a maintenance nightmare.    But a great IDE can handle it.  We didn't have those back then, and our computers were powered by coal and steam. 

 

All in all, yes, I agree with you, especially when projects grow larger.  I appreciate your comments, T, keep them coming.  I am not a very good coder, so we could use all the input we can get on this.

[Wingnut]

Hi team!  https://github.com/BabylonJS/Babylon.js/wiki/06-Lights has been adjusted.  I added a section about .direction... just below the DirectionalLight picture.  It is more wordy than I wanted it to be, and PLEASE check it for mistakes. 

 

Adjust at will, or I will modify it as wanted.  Or, reject it, and I will try to use a different method, or try to make it shorter, or something.  Tell me your thoughts, ideas, what ever.  Don't worry about hurting my feelings, and don't bother kissing my butt.  Shoot straight.  Tact/diplomacy gets in the way when doing this kind of work.

 

I used some BOLD words.  Can remove... but... I like bold. 

 

I also added a short line above the picture, to tell users that the DirectionalLight is created at default position (0,0,0).  It seems odd to me that the spotlight constructor has a position setter in the 2nd arg of its constructor (making it an exceptionally long constructor), and directional light does NOT do that.  hmmm.

 

Puppy-Syndrome:  Why did you do it THAT way?  hehe.  NIP?  (necessary initial property)?

 

The mod(ification) about backfaces and normals is still to come.  I am still thinking about its wording and making sure I know what I am talking about.

 

Input welcomed from everyone and anyone (although we might not HEED said input) 

 

Fire away!    I hope everyone is well.

[Wingnut]

Hi gang.  Here is a picture that I have prepared, in order to help teach backfaces and normals, as they relate to lights.

 

http://urbanproductions.com/wingy/babylon/misc/normals03.jpg

 

The left plane has its un-culled backface facing us, its normals arrows facing away, and showing no light affect from the spotlight and pointlight in the low center of the picture.  The right plane, its normals arrows facing the viewer, showing the affects of the spotlight and pointlight.  Can we afford the needed length of a "Extra Information About Backfaces, Normals, and Lights" (with this picture) at the bottom of the lights tutorial?  Or does that make the lights tutorial too long?  Thoughts?

 

Maybe, we put a link at the bottom of tutorial #6... to another document... about planes, backfaces, normals, and how lights work with them.  See, talking about normals... could lead to questions about per vertex and per face, and questions about "What IS a backface?" Our new tangent tutorial could analyze the CreatePlane function and teach about clockwise and counter-clockwise plotting, and how the user can reverse the normals, and how they can use two planes to make double-sided normals, etc etc.

 

This "tangent" tutorial (not really part of the "Basic Series" but yet it is so), could be rather large.  It COULD help stop many beginner questions.  If it were big enough, we could actually teach how to make a building wall with holes for windows and doors... via plotting (WITHOUT needing to use CSG boolean subtraction). 

 

We could start them out by teaching about backfaces and normals and cw/ccw (clockwise/counter-clockwise)... and take them on the "Make a two-sided wall with windows and optional door" adventure trip.  The wall could have its normals set correctly for two-sided (in-side and out-side faces/planes) and maybe we could even figure out a way to texture the out-side of the wall in ONE way, and the in-side in ANOTHER way.  Then the last thing, we get back to lights, and light up that new wall, inside and outside.

 

Yes, a huge undertaking.  For now, we could add a very basic few lines about lights, and normals, and maybe put my picture into tutorial #6.  But maybe, for a longer-term plan, we think about, and begin building, the much bigger tangent tutorial.  Thoughts?

 

Here is one question I have.  If we did 'plot' a two-sided wall with two windows and a door, CAN we texture/color the inside wall in ONE way, and the outside wall in ANOTHER way?  I think that is called 'texture mapping' in 3D Max. 

 

Or does 'texture mapping' with babylon.js require the plotting of two identical planes, one with normals facing out, and one with normals facing in, and then texture/color them separately, and then build 4 cap planes?  (wall end-butts).  Then manually position and rotation.  (I should probably test it myself and learn). 

 

Backfaces, normals, and planes, are all VERY related to walls.  Walls are a popular newbie mesh/shape.  Teaching how to plot vertices and work-with normals/lights, is an important part of making walls. 

 

Yes, Ehret's 6-part plotting tutorials are nice: https://ehret.me/webgl-experiment-part-1-your-first-polygons/ but I think we might need to do our own.  Planes, normals, lights, and walls... the adventure begins.    Thoughts?  Ideas?  Thanks!  View this thread in French... http://tinyurl.com/oxhxzxy  We are on page 2. 

[GameMonetize]

I think that your picutre fits well into tutorial6. BTW for additional stuff not directly linked to lights, I sugges creating a new page and adding a link to it. Just for the sake of simplicity

 

 

 

 If we did 'plot' a two-sided wall with two windows and a door, CAN we texture/color the inside wall in ONE way, and the outside wall in ANOTHER way?  I think that is called 'texture mapping' in 3D Max. 

This is dual-face mapping and no we cannot. You have to define two planes for that

 

 

Backfaces, normals, and planes, are all VERY related to walls.  Walls are a popular newbie mesh/shape.  Teaching how to plot vertices and work-with normals/lights, is an important part of making walls. 

Backfaces and normals are related to faces. Everything is babylon.js is composed of faces. this is not only related to walls

[Wingnut]

Right.  Not only related to walls.  But building walls is a good place to teach backfaces, normals, and even lights.  Spheres, torus, and other closed mesh, there it's not so easy to teach those things.  Walls, easier.  Easier to teach cw/ccw plotting, low amounts of vertices, low amounts of normals, etc.  Flat things.   Graph paper and grids... 2D.  Easy for us puppies.  Thx for info, too.

[Wingnut]

Hi!  The 'backfaces and normals' section has been added to Tutorial #6 ( https://github.com/BabylonJS/Babylon.js/wiki/06-Lights ).  Adjust at will.  The picture should probably be moved to a BJS directory somewhere.  It now belongs to Team BabylonJS.

 

I used no bold.  I used a few italics... adjust freely.

 

I did hard thinking about which words to use... for aiming, aimed-at, aimed-towards, toward, facing, etc.  Apparently, the British use 'towards' most often, and the North Americans use 'toward' most often.  I used 'facing toward' and 'not facing toward'.  Adjust at will.

 

Deltakosh or anyone... if I said something that was wrong in that section... feel free to fix it, but also, please teach me where/how I was wrong.  Thanks!

 

Everybody, please submit ideas and opinions if you have them.  How to clarify, how to briefen, how to make those links like Gryff did in http://www.html5gamedevs.com/topic/5090-trigger-zones/#entry31758 (the Zones Test link, that does not include the whole url as the link).    I like that.

 

I think that is done with bb code.  Gryff or anyone, teach me how to make those links with the hidden urls, huh?  Use PM if you wish.    I hope everyone is well!