Learning - snags / hangups

seltzy · December 2016

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.

sausage · December 2016

Thanks for outlaying all this, seltzy. There's a lot here I can easily knock off. Some others will need some time.

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.

seltzy · December 2016

Here's some code for bootstrapping configuration.

orxSTATUS orxFASTCALL Bootstrap()
{
  orxSTATUS eResult = orxSTATUS_SUCCESS;

  // Adds default release config paths or do other stuffs
  orxResource_AddStorage(orxCONFIG_KZ_RESOURCE_GROUP, "../", orxFALSE);

  // Loads a specific config file
  /* orxConfig_Load("SomeSpecificConfig.ini"); */

  // Done!
  return eResult;
}

int main(int argc, char **argv)
{

  orxConfig_SetBootstrap(Bootstrap);

  // Executes orx
  orx_Execute(argc, argv, Init, Run, Exit);

  // Done!
  return EXIT_SUCCESS;
}

#ifdef __orxWINDOWS__

#include "windows.h"

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow)
{

  orxConfig_SetBootstrap(Bootstrap);

  // Executes orx
  orx_WinExecute(Init, Run, Exit);

  // Done!
  return EXIT_SUCCESS;
}

#endif // __orxWINDOWS__

sausage · December 2016

Hi seltzy, I've written articles to address 2 and 7.

Would you mind reviewing these?

http://orx-project.org/wiki/tutorials/changing_default_config_file
http://orx-project.org/wiki/tutorials/basic_physics_and_collisions

seltzy · January 2017

The physics one is pretty solid. Good work on that one.

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 · January 2017

Thanks for taking the time to list all those issues!

Sure, how do you think this might be best conveyed?
Sausage already started to address this point in the wiki.
I'll change those to remove that confusion. Then we can probably modify the camera tutorial page on the wiki to expand on the concepts.
Do you think you could submit a PR with an annoted config file? That could be very helpful.
That's how the sprite sheet was laid out, so it's not actually wrong, just less conventional. In the new tutorial, I re-worked the sprite sheet with a more conventional western writing direction.
We should probably have a wiki article about this.
Those actually directly reflect the organization behind the physics engines themselves, like Box2D & co. Maybe we should direct people to wikis dedicated to 2D physics engines instead of re-writing everything ourselves, and simply giving the mapping between the concepts (ie. bodypart -> fixture/shape, ...)
Good idea, don't hesitate to contribute to the wiki, Sausage can help you there as needed. If you need write access, just lemme know.
Ditto.
This has now recently changed, but you already know that.
It is indeed a misnomer, it used to be speed (ie. the magnitude) but was then decoupled with the direction, though we kept the name. I could add an alias to Velocity in config and code, but that feels like a lot of duplication for not much benefit. If enough people think it'd be useful, I don't mind adding them though.
I'll let you and Sausage address this one.
Good idea. I could whip a quick graphviz/dot graph at some point. Also, I was thinking of maybe supporting some kind of debug visual display of graphs, not sure if it'll be part of orx itself or a tool on the side (using graphviz/dot). Any suggestion?
The Solid property is what you need. We'll have to check if it's illustrated somewhere in a tutorial.
Good idea.
This property doesn't exist anymore, we'll have to update that tutorial.
The names are dimension-agnostic as supporting 3D in the future is a possibility. Actually someone started a Bullet-based physics plugin (ie. 3D) at some point, but it never got released. But yes, if you think of it as 2D only, it's definitely weird.
We should probably illustrate this as well in the beginner's guide. Image space is in pixels, there's no ratio there. World space is also in pixels as the 1:1 conversion from image space is hardcoded and can't be changed. That leaves us with physics space and sound space which both have customizable ratios. I can also display the active ratio in the runtime profiler page if you think that'd help.
Mmh they should be, as far as I remember. However speed itself is independent of delta time.
Indeed.
We should also probably cover GUIDs, which is a safe way to retrieve any structure inside orx, which prevents crashes when trying to access deleted objects. They do come with a cost though, so local caching might be advised.

iarwain · January 2017

To sum it up, I'll address #3 right away and we can discuss #11, #13 & #18 on the chat.

iarwain · January 2017

I just pushed a commit with changes for #3.

sausage · January 2017

Point 12 is fixed, plus a couple more typos around it:
http://orx-project.org/wiki/guides/beginners/shooting_and_spawners

seltzy · January 2017

iarwain wrote:

Thanks for taking the time to list all those issues!

My pleasure.

iarwain wrote:

Sure, how do you think this might be best conveyed?

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:

Do you think you could submit a PR with an annoted config file? That could be very helpful.

Sure, I'll look into doing that this week.

iarwain wrote:

Good idea, don't hesitate to contribute to the wiki, Sausage can help you there as needed. If you need write access, just lemme know.

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:

Good idea. I could whip a quick graphviz/dot graph at some point. Also, I was thinking of maybe supporting some kind of debug visual display of graphs, not sure if it'll be part of orx itself or a tool on the side (using graphviz/dot). Any suggestion?

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:

This property doesn't exist anymore, we'll have to update that tutorial.

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:

We should also probably cover GUIDs, which is a safe way to retrieve any structure inside orx, which prevents crashes when trying to access deleted objects. They do come with a cost though, so local caching might be advised.

I didn't even know that was a thing. Knowing about more best-practice-like stuff like that would be very useful.

sausage · January 2017

seltzy 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?

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.

iarwain · January 2017

seltzy 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?

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 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.

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 didn't even know that was a thing. Knowing about more best-practice-like stuff like that would be very useful.

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?

seltzy · January 2017

iarwain wrote:

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.

My account name should be the same as it is here.

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.

Well, having an illustration in one of the tutorials would easily suffice for now. IDE you say?

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?

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.

iarwain · January 2017

Added you as a wiki editor.

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

sausage · January 2017

iarwain wrote:

For this kind of discussion, I feel this forum is too antiquated and the chat not adapted, so we can either head to the orx-dev group or the Trello boards Sausage created a while ago. What do you think?

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.

iarwain · January 2017

A separate chat room is still not convenient. We don't really need a discussion, we need a way to maintain a list with a check mark for things that are covered. We can use a wiki page if you'd rather.

seltzy · January 2017

Also, for the record, I'd like to elaborate on the Speed vs Velocity issue. I posted this in chat, but I think this deserves a forum post.

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.

[PlayerStats]
PlayerSpeed = 600.0 ; How fast the player can move
PlayerJumpPower = 2.5 ; Multiplier for jumping

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.

orxFLOAT fPlayerSpeed;
orxFLOAT fPlayerJumpPower;

So far so good.

Now for movement. Here's where things start getting weird.

orxVECTOR vMove;

  if (pstPlayer == orxNULL) {
    return;
  }

  orxObject_GetSpeed(pstPlayer, &vMove);
  vMove.fX = 0.0f;

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.

if (orxInput_IsActive("MoveRight")) {
    orxObject_SetFlip(pstPlayer, orxFALSE, orxFALSE);
    orxObject_SetTargetAnim(pstPlayer, "SoldierRun");
    vMove.fX += fPlayerSpeed;
  }
  if (orxInput_IsActive("MoveLeft")) {
    orxObject_SetFlip(pstPlayer, orxTRUE, orxFALSE);
    orxObject_SetTargetAnim(pstPlayer, "SoldierRun");
    vMove.fX -= fPlayerSpeed;
  }
  if (orxInput_IsActive("Jump") && orxInput_HasNewStatus("Jump")) {
    vMove.fY -= fPlayerSpeed * fPlayerJumpPower;
  }

Okay this looks a bit better, I see scalar values getting assigned to vector components. More familiar semantics.

orxObject_SetSpeed(pstPlayer, &vMove);

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.

sausage · January 2017

iarwain wrote:

A separate chat room is still not convenient. We don't really need a discussion, we need a way to maintain a list with a check mark for things that are covered. We can use a wiki page if you'd rather.

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:

http://orx-project.org/wiki/todo

Then I can scratch the items out as they are completed.

iarwain · January 2017

Mmh, my suggestion was more that I would list all the features of orx, obvious and hidden, small and big, and then we could do the cross-referencing with the wiki itself.

sausage · January 2017

I see. I guess something like a google spreadsheet would work.

If it's open and hidden, I could still get in to help.

Two columns?

FEATURE # COVERED-AT
FX # http://orx-project.org/wiki/tutorials/fx

iarwain · January 2017

Sure, but wouldn't a table in the wiki work just as well with the advantage of not being a new tool?
Also that could be made public in some way, such as a table of content or the like?

sausage · January 2017

You can make a formatted table for display using wiki markup, but it can't be used like a spreadsheet:

http://orx-project.org/wiki/wiki/syntax#tables

It might do.

Howdy, Stranger!

Categories

In this Discussion

Learning - snags / hangups

Comments