Tutorial needs work

Bugs
#1

Like many (I imagine) I am trying to work through the Getting Started tutorial, but I can’t help but feel that it needs work or at least a once over by a technical writer. So far:

  1. No mention of the constant need to save things before they become usable (unlike other engines). For example, when adding a sprite component to the game objects for the ground (note: we’re not told how to do that, clicking around you find it eventually), you need to have saved the ground.atlas before the images will appear in the “Default Animation” dropdown. We are not told this.

  2. We are told to “Add “ground.collection” to “main.collection””, but we are never told how to do this. I eventually found out, but a decent tutorial would say how.

  3. This is the worst one. We are told to add seven Game Objects for the ground pieces and then suddenly they are there in a row without any explanation as to how. I guess we’re supposed to modify the positions, but it turns out there are two positions, the position of the Game Object and the position of the Sprite Component. So we look at the images in the tutorial and see that for the first image ground0 has had the Sprite Component position changed to (114, 0, 0) and in the second image ground5 has had the Game Object position changed to, I think as a red circle blocks some of it, (1140, 0, 0). So which is it, Spite Component or Game Object? Ideally a tutorial would say not only what to change but what to change it to.

4 Likes
Please Fix Tutorials? :(
#2

Thanks for feedback. I’ll add clarifications to the tutorial.

We have a 10 part video version out as well. It’s not super detailed in exactly how you perform the basics like saving, adding components and such, but is more tuned towards explaining how things fit together in the engine. Maybe it’s helpful anyways. Check it out at https://youtu.be/DulOdWitN8E

2 Likes
#3

You can also try the Car tutorial in the meantime. It’s a bit more basic and is also shorter. Check it out here http://www.defold.com/tutorials/car

You might also want to check out the manual on the scene editor here: http://www.defold.com/doc/scene-editing

1 Like
#4

Thanks for getting back to me.

I managed to work my way through it anyway. I am a programmer by trade, I was just thinking more for new users. It may be worth making the finished project available so the user can check how it is supposed to be, in the same way that other tutorials are.

One other thing I noticed today is that the third part of that tutorial doesn’t mention that you need to create a factory for the coin.

2 Likes
#5

So I’m now on the Magic Link tutorial.

It might be helpful to point out that the background should have a z-position of -1, otherwise all blocks after the first column will be rendered behind the background.

The block colours must have changed during development as the tutorial states:
local colors = { hash(“red”), hash(“green”), hash(“blue”), hash(“yellow”), hash(“grey”) }

However what is needed is:
local colors = {hash(“orange”), hash(“pink”), hash(“blue”), hash(“yellow”), hash(“green”)}

Similarly, a bit further down a message “make_red” is implemented, but red isn’t one of the available colours.

3 Likes
#6

Thanks for spotting! I’ll update that one too.

1 Like
#7

If it is OK with you, I’ll keep updating here with stuff that doesn’t seem right.

In the “Mark Links” section you need to change in board.script:
local centeroff = 2.5
to
local centeroff = vmath.vector3(8, -8, 0)

In the on_input function the tutorial references a non-existent function. The downloadable complete project doesn’t have it, so I guess it was either removed or never implemented:

self.chain = {}
– Empty chain clears connector graphics.
connect_chain(self, x, y)

Instead the old code for removing connector graphics should remain.

In the magic_fx object section it’d probably be a good idea to say which images the user should use for the “magic” and “light” sprite components (I found out by checking the completed project which I have open in another instance of the editor). It may also be useful to mention that the block of code goes in block.script and that the factory for the magic blocks needs to be created. This section also references a #cover section in the code which is never actually mentioned before, so the user has no idea what it is or how it should be created.

4 Likes
#8

More a constructive criticism than anything else, the last section (where the GUI is put on) seems very rushed. It flies over things (“Step 1 is to create a “main_menu.gui” and set it up with a “Start” button, a title text and some decorative blocks.” with no further explanations) and brings in a new concept, collectionproxy, as if it is something the user should already know about. I know the user could/should go to the documentation to find this out but the goal of a tutorial should be to tell you what to do, not give you a list of things to look up elsewhere (or, as I have had to, get a copy of the completed project, run it in another instance of the editor and look for values).

Anyway, the whole GUI section is mixed in altogether whereas really they are two very separate things.

  1. The main menu and how to go from that to the game (using the collectionproxy).
  2. The in-game GUI.

I just spent an hour debugging trying to work out why, after making the changes to load the board whenever blocks slid down older version appeared behind them. I was convinced I had done something wrong with enable/disable of various things (btw I also found out that unless the name for the collection is set the sockets don’t work. “main:/” failed even though the editor itself doesn’t rename the collection to that - something the tutorial probably should mention when creating the collections). It turns out that I still had the test board setup msg.post() calls in board.script::init(), something we are told to remove seven pages down (on my 2560x1440 monitor) after literally all the other GUI stuff is done. Surely this should be said earlier, allowing the user to check that going to the board from the start screen works? Because people will try that and then get worried when it doesn’t work …

Anyway, I think I am done with the tutorial now, so no more annoying posts from me ;o) I’ll be starting on a game that I am porting from Unity tomorrow …

2 Likes
#9

Thanks for all the feedback! We’ll definitely use it to make the tutorials better - and free of errors. :slight_smile:

1 Like
#10

Glad to be of service!

1 Like
#11

Not sure if I should bump this or just post a new thread, but I’ll do the former. Maybe it’s a good idea to have one single thread for all tutorial-related feedback?

In the simple runner tutorial (part 2) under SPAWNING PLATFORMS.

“Add two factory components to the “controller” game object in “level” collection”

But nowhere does it say that you have to go into the properties window of said factories and change the prototype to the platform.go and platform_long.go. Failure to do so will result in multiple errors in the error log when building+running the game:

“Connection refused: Connect”
“The workspace exited with unsaved changes in the previous session; refreshing workspace to recover changes.”
“Application error”
“The workspace exited with unsaved changes in the previous session; refreshing workspace to recover changes.”
“Unhandled event loop exception”

Setting a prototype for the factories resolves this issue and the user can continue with the tutorial.

EDIT: I see now that the tutorial also fails to mention that the name/Id of said factories has to be platform_factory and platform_long_factory. The controller script refers to these objects by those ID’s.

EDIT2: Same tutorial, just before going to step 3. The tutorial tells you to change one thing in platform.script, and then you are told to reset the level at hero death. But it doesn’t say where we can find that code. It is not located in platform.script but instead in hero.script

3 Likes
#12

I also think there is an error with the spawning mechanic of the coins
the code after the line:
"And finally add a couple of lines to “controller.script”:"
uses a variable and doubles for every new “long” platform. This values goes bigger and bigger and is never reseted.
It looks like we should use a local variable here:
`-- Maybe spawn a platform at random height
if math.random() > 0.2 then
local h = platform_heights[math.random(#platform_heights)]
local f = "#platform_factory"
local number_coins = coins;
if math.random() > 0.5 then
f = "#platform_long_factory"
number_coins = coins * 2 – Twice the number of coins on long platforms
end

            local p = factory.create(f, vmath.vector3(1600, h, 0), nil, {}, 0.6)
            msg.post(p, "set_speed", { speed = self.speed })
            msg.post(p, "create_coins", { coins = **number_coins** })
            table.insert(self.spawns, p) 
        end`
1 Like
#13

No, look at the line (around line 23):

local coins = coins

Here we declare a local “coins” that lives only in the scope of “if math.random() > 0.2 then”. It shadows the local that is declared and initiated at top level in the beginning of the file. Your proposed fix just renames the if-local “coins” to “number_coins”.

That said, it is perhaps clearer to use a different name.

1 Like
#14

how ever, this wasn`t working for me. i have to rename the variable to avoid creating 3 -> 6 -> 12 -> 24, etc coins everytime the line 26 hits.
using windows 10

1 Like
#15

That must be some other problem. Can you post the full code?

1 Like
#16

Thanks everyone for the feedback. I’ve published an updated version of the tutorial on the site. It will most certainly need further work (and might contain new errors) so keep the feedback coming!

Check it out at http://www.defold.com/tutorials/getting-started

2 Likes
#17

Hello there,
I’ve been working with the tutorial during GGJ16 and I found a mistake.
On page http://dashboard.defold.com/projects/8052/tutorial/2 (the running frog game) and “Now add your hero game object “hero.go” to the “level.collection” at a suitable position. If you want you can try to play the game now, and watch your hero fall through the ground!”, it should be “ground.collection” not “level.collection”.

Defold is my first game engine and I’m really enjoying it so far. Thanks!

3 Likes
#18

I’ve encountered a few errors in the tutorial myself that seem to be causing problems.

I’ve gotten to the part of the tutorial where we’re supposed to be resetting the level when the player touches spikes, and when setting up the “controller.script” file for that, the line
"self.spawns = {} 1"
gives a build error:
"unexpected symbol near ‘1’ ".
Putting the 1 inside the curly braces seems to fix this issue and allows the game to build.

The other problem is that the platforms have stopped spawning. Whenever the controller script hits the line:
"local p = factory.create(f, vmath.vector3(1600, h, 0), nil, {}, 0.6)"
The console begins printing the following every frame:
“WARNING:GAMEOBJECT: Fragment has no meaning for this function: (null)”

I am not sure why this is happening, because earlier in the tutorial (before adding the spikes) the platforms were spawning as intended. It was also not a particularly helpful error message given that it didn’t indicate what script or line of code was causing the error. I had to make an educated guess and start commenting out lines of code to narrow it down.

1 Like
#19

When it comes to “self.spawns = {} 1” the one (1) simply links to the text below the snippet of code that describes what the line does. It should not be included in the actual script file.

“WARNING:GAMEOBJECT: Fragment has no meaning for this function: (null)” is a recently introduced warning indicating that you’re using a URL containing a fragment when you for instance try to set a game object scale or something like this. @sicher who knows the tutorials better than I do can probably tell you whats wrong.

1 Like
#20

Thanks for the response. It’s odd that the 1 is showing up when I have the example set to “View” raw in that case.

1 Like