Hi all. I'm a newbie learning the ropes of orx and am in the process of compiling where I've hit bumps and snags and such. Hopefully this helps improve the tutorials for other learners, though a good lot of this may well be due to my own ignorance.
Before I begin, thank you everyone who has contributed to the wiki and tutorials. It really does help. It's looking much more approachable than it did a few years ago when I first tried using orx.
I'll update this periodically as I come upon new challenges. Here's what I have so far.
- My biggest initial hangup every time I've started was what options there were for project setup - it's super flexible but tutorials led me to beleive I should do it a certain way that I didn't like. This is more particular to me since I'm picky about having a good template project setup. I think I've figured out a setup that I like, but seeing a list of possible suggestions to illustrate this flexibility would be helpful to newcomers.
- none[strike]Another hangup was the fact that the config file is next to the executable - it would be nice to note that this can be changed in code.[/strike]
- The next challenge was understanding how camera and viewports interact. [strike]Seeing a lot of sample config files use display resolution for frustum dimensions led me, someone who had forgotten the nuances involved in selecting frustum size, to think that this was the norm and should be conformed to.[/strike] Having some more pictures in the viewport/camera tutorial that illustrate how the camera behaves in relation to objects would be helpful. Explaining what kinds of things to take into consideration would be good. Explaining what worldspace looks like in the context of orx would also help. Having a solid reference for the user to anchor their mind to is essential for this.
- AutoScroll was a temporary confusion. At first config files will appear to be black magic, so the language here may suggest that the camera scrolls with X instead of configuring parallax scrolling behaviour. The Scrolling tutorial on the website explains the many nuances of the configurations for Cloud, Sky, and Camera, but the config file in the repository does not and the explanations in comments are not as descriptive as they could be.
- none[strike]The animation tutorial makes frames in wrong order - they increment down each column, not each row.[/strike]
- I assumed WatchList automagically hotloaded objects at runtime - didn't occur to me that pre-existing objects wouldn't change - totally magical thinking in retrospect
- none[strike]The physics tutorial doesn't really explain the motivations behind there being body and bodypart. I can imagine why, but clarifying their differences and giving a brief explanation of why the properties available to them differ might be useful for some users who are unfamiliar with 2D physics systems. If these are covered elsewhere on the wiki, a link would suffice.[/strike]
- In general these tutorials cover only what is needed, which is good for brevity but bad for those who are intuitive and curious. Having links to more detailed descriptions (like wikipedia articles do) would add a significant level of polish to these tutorials.
- This is very minor, but having prev and next links would also be nice. I only say this because some browser plugins use those as a way to streamline browsing - I use one such plugin that adds keyboard shortcuts for those. Minor annoyance. Not a huge issue.
- The changing direction tutorial doesn't seem to work for idle animations. I think this is because no idle animations are defined. This may be a mistake on my part, but if it's not, please show why this happens in the tutorial and fix it (much like in other sections of the tutorials). It also takes a more code-oriented approach than the official tutorial files. [strike]I think overall suasage's tutorial involves less typing. In general, I think this is what is important to strive for as a programmer. It calls into question what the advantage is to the full config approach for animations. It'd be nice to understand the pros and cons of each. The anim tutorial files are quite large and intimidating by comparison, but if there was a way to crunch that file down a bit that'd be ideal.[/strike]
- The property name "Speed" is somewhat misleading. Technically speaking, as a Vector, it describes Velocity. When I think Speed, I think of a Scalar value. Overall this is me being picky about naming conventions. Most people don't know/care about the difference. It mostly struck me as strange, so it didn't kill momentum too much.
- none[strike]On the shooting tutorial, there's a minor typo. Where it says "This spawner can shoot BulletObjects. It can shoot one at a time with 0.02 milliseconds between shots" is inconsistent with the config above it; the interval is 0.1, not 0.02.[/strike]
- Animation tutorials talk about animations being stored as a directed graph but there's little information illustrating that. Adding a picture that demonstrates what such a graph looks like from the config in the tutorial would be much better than a wikipedia link.
- Colliding with the star kills the player's momentum since they are physically colliding with it. It'd be nice to know how to prevent that from happening. Imagine if that happened when picking up rings in Sonic, or coins in Mario.
- Just remembered, in the jumping tutorial, the player can actually fly if they repeatedly tap jump. Not a bad idea to point this out and perhaps show people how fix it.
- The spawning monsters seem to still be ground sliding by the end of the tutorial. I couldn't really tell much of a difference between before and after setting AllowGroundGroundSliding=false. Same sorta goes for angular damping. Apparently AllowGroundSliding was removed.
- The naming conventions for physics types isn't quite what I'd expect. Box is okay I think, but does sphere really make sense in a 2D game? I sorta just guessed it would be circle. Threw me off for a second. Not a huge deal, just a bit odd.
- I was completely ignorant of the fact that image space, physics space, world space, and sound space each have their own ratio to pixels. It led to quite a bit of confusion, particularly with the difference between world space and physics space. Although a lot of that is abstracted away from the user, I think it'd help to have that information in one place. This sort of relates back to my problem with understanding the world size. It may be worth having a short wiki page just on this relationship. I think part of this stems from being a user who had been using IDE-like engines with world editors that give you a spacial sense of the world right off the bat in no unclear terms. When you have a world editor that you can prototype in and experiment with engine features these differences become apparent, but with library-like engines the user doesn't have this intuitive knowledge as immediately. To get the same effect, this information needs to be demonstrated in some other way. This gets back to giving the user an anchor to ground themselves in their sense of all aspects of the game world.
- I'm pretty sure none of the tutorials use deltatime. I'd suggest registering an Update method that uses a clock instead of using Run. You'll probably need to adjust speeds as well.
- It may be wise to set velocity instead of applying impulse when moving characters around. It's better for determinism, which is usually what we want for gameplay.
- Double-check hero's survival tutorial. When setting hero's lifetime to 0, there's a possibility of a crash due to it being... well... gone but not exactly null.
- In terms of dealing with deprecation problems on the wiki, a solution that's similar to http://en.cppreference.com/ would be very nice. They annotate all behavioural changes to the API with versions/standards that were in use at the time. That way anyone that references it can clearly see what got deprecated when. That might be hard to do with the current doxygen/wiki setup, but something to think about. Having a no-nonsense way of seeing when tutorial and documentation are out of sync with the current state of Orx is essential. #8 should help mitigate this issue, but won't completely solve it. Perhaps if there was a good way to automate the tutorials with unit tests, it'd be easier to see when things get out of sync (at least with some things).
- The API dox are really hard to use since the search box doesn't let you search for middle-parts of a word. If I want to find GetString, I need to know what my target result starts with. This may mean typing in orxConfig_GetString, which maybe I didn't know that was I was looking for was under orxConfig. This also makes it impossible to explore the API documentation in a meaningful way without using some sort of command line wizardry on the source.