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.
Might start with point 2.
Is there a chance you have implemented the code to do this yet? If so, could you pop it through to me and I'll write something up.
Would you mind reviewing these?
I think we discussed some changes for the other tutorial. The main point is to distinguish use-cases for the things we put in bootstrap, and phrase them in terms that describe their usage as opposed to their technical meaning alone.
iarwain wrote: Well, there are quite a few tutorials out there right now on project setup in terms of IDE selection, though they appear to be a bit dated. It may be good to dedicate a tutorial to loosely consolidating them and explaining that a project can be organized however you want. Having people share their templates and preferred setups may illuminate how to express that.
iarwain wrote: Sure, I'll look into doing that this week.
iarwain wrote: I suppose it wouldn't hurt to have write access. How does that work? Would I edit things as I come across them, or discuss before editing?
iarwain wrote: I think that if a graph is to exist anywhere, it'd be best to start with the tutorial/docs. I haven't used the profiler yet, but having something in debug mode seems very useful. I haven't felt the need for it, but I haven't explored animations in depth yet.
iarwain wrote: Yeah, though I think it's still referenced in a number of places in the wiki. May want to do a search for it.
iarwain wrote: I didn't even know that was a thing. Knowing about more best-practice-like stuff like that would be very useful.
If you see it and know it needs fixing, just bang it in and get it done I reckon. That way, things get fixed and move along quickly.
But if you have any doubts on an edit, a quick chat is the best.
Create an account on the wiki, tell me what it is and I'll give you editor access. Regarding your second question, best to see with Sausage directly. There's also a discussion thread on every page that can be used for suggestions.
I had a quick look at my options tonight, and I think it won't be as easy as anticipated, so I'll put it on my todo list for an eventual orx IDE.
I should probably list all the features that have been added over the last few years so we can check if there's some coverage to be added to the wiki. For this kind of discussion, I feel this forum is too antiquated and the chat not adapted, so we can either head to the ord-dev group or the Trello boards Sausage created a while ago. What do you think?
Well, having an illustration in one of the tutorials would easily suffice for now. IDE you say?
I've used Trello before, though I'm not sure how good it is for discussion. Would be a worth trying both and see which one is a better fit. I didn't know there was an orx-dev group.
IDE, yes, one day, when I have enough time or if I can make a living based on orx, be it being indie with games made with orx or with a bigger community and doing support.
It's not much of a discussion, more of a laundry list and ticking off the ones that are covered. I'd use Google Keep for that, but I know some of us rather stay far away from anything Google.
Here's the orx-dev group: https://groups.google.com/forum/#!forum/orx-dev
Rather than another system, how about just a separate chat room, as it is just to temporarily nut out what articles are required. Any discussion that leads to needing a wiki article can be added to the wiki's todo page.
Overall, it's not a huge problem since the terminology is consistent. Adding an alias would likely increase confusion while present (unless it highlights Speed as being depreciated). Removing Speed (or correcting its functionality) would be an expensive breaking change that may be best saved for a major version change, such as the inception of 3D.
My feeling is that the real issue with speed comes in when naming variables. My first encounter with that was writing movement code.
Let's say I have a config file that specifies player stats. Here there's already the potential for confusion. It's possible that the Speed attribute is used elsewhere in my config file using Orx's semantics, which puts me in an awkward situation for naming my variables.
Now in code, lets say we have those two variables yanked from the config into the following variables. So far so good.
Now for movement. Here's where things start getting weird. Wait, why is speed getting stored in vMove? That can't be right. Why aren't those speed variables involved here? GetSpeed must be storing a vector. That seems a bit odd. Oh well, let's continue. Okay this looks a bit better, I see scalar values getting assigned to vector components. More familiar semantics. And there it is again. After having used those speed variables on vMove, this line sticks out like a sore thumb.
This gets even weirder in cases where I need to get the magnitude of the "speed" for say, checking whether the character should animate while on the ground.
This weirdness is a product of my own naming conventions clashing with Orx's in some pretty trivial movement code that I'd expect to see in most platformers, albeit a bit brittle. It's possible that I'm doing-it-wrong™ and there's a better Orx-style-way of doing it (an Orxism, if you will), which has often been the case so far.
On that note, it's probably worthwhile to dedicate a tutorial or example to more robust platformer movement. There's plenty of behaviour that's not represented here that would be nice to see.
Rather than go to the labour of listing the things that are covered, we just continue to list the things that are required on the TODO page:
Then I can scratch the items out as they are completed.
If it's open and hidden, I could still get in to help.
FEATURE # COVERED-AT
FX # http://orx-project.org/wiki/tutorials/fx
Also that could be made public in some way, such as a table of content or the like?
It might do.