ConstructActor very confusing; Comments do not specify what each segment of the array does.

[T-SquaredProductions]

For a random example: For the floating star actor, I don't know what the various numbers and logic switches do: ConstructActor(SPR_STAR, x, y, F, F, F, F, ActPrize, 0, 0, 0, 0, 4);

On one hand, I thought the final number in the array was for frame count, but it doesn't make sense for other actor constructors.

[smitelli]

The function definition for ConstructActor() makes it a little clearer. The 13 parameters are, in order:

• sprite: The sprite number (or SPR_* define) to use when drawing the actor.
• x: Starting X position in the map.
• y: Starting Y position in the map.
• force_active: If true, the actor starts in an activated state -- it thinks and moves even though the player cannot see it. If false, the actor is frozen until it scrolls into view.
• stay_active: If true, an actor that became activated will stay that way if it scrolls off the screen. If false, the actor will go back to its frozen state once it can no longer be seen.
• weighted: If true, actor is pulled down by gravity during each iteration of the game loop. If false, gravity doesn't move the actor (it can still move itself in a way that simulates gravity, however).
• acrophile: If true, actor will willingly walk off ledges. If false, the actor considers a ledge to be impassible (like a wall) and must stop/turn around.
• tick_func: The name of a function to run each time the game loop processes this type of actor. These functions do a lot and some actor types do things in wildly different ways than one might think by looking at other actors.
• data1 - data5: Initial values for the data1 - data5 fields in the actor's memory. These are named vaguely because there is absolutely no rhyme or reason to how these are laid out. Sometimes it's a frame count, sometimes it's a direction, hit points, cooldown flag, temp variable... The only way to know for sure is to skim the function referenced by tick_func, as well as the TouchPlayer() case(s) for the sprite type and/or DestroyBarrel().

For the example you gave specifically (looks like ACT_STAR_FLOAT), I can quickly trace through and explain what the data arguments are. The tick_func is ActPrize(), so I jump to that function to see:

• data1: If data5 was 1, this would be the width of the actor, used to place random sparkle effects.
• data2: If data5 was 1, this would be the height of the actor, used to place random sparkle effects.
• data3: Temporary storage for "half-speed" throttling. Initialized to 0, but not externally relevant.
• data4: If 0, the sprite frame advances every frame of the game loop. If nonzero, it advances every other frame of the game loop (in other words, half-speed). If nonzero, the actor is also disqualified from having random sparkle effects. This must've mattered to the original authors, but I can't fathom a reason for it right now.
• data5: The total number of frames in this actor's animation loop. If the value is 1, the actor doesn't animate and it could be subject to random sparkle effects.

There are other side-effects and interactions in there as well. If data1 is nonzero, the actor is also drawn flipped. This is supposed to make it possible for ceiling-mounted prizes, but it interferes with "sparkly" objects -- if you look at the actor tiles and compare them to what the game draws, "sparkly" prizes are drawn flipped too because their data1 holds a width which is nonzero. The game is full of kludges like that.

Needless to say, every actor type is different. If there was a way to unify the behavior with a more useful name, I would have done so. ;)

An aside: Values for true/false are abbreviated as T/F here for space reasons, and I tried to convert all numeric constants I was sure about to named things to make it a little clearer what was being passed. Unfortunately for many of these, you'll have to read the source.

[smitelli]

This is also quite important -- it specifies what happens when the player touches an actor of the SPR_STAR sprite type.

[T-SquaredProductions]

Thanks. I'm not trying to act dumb or look for hand-holding. 😜 I'm just not familiar with the more complex intricacies of the program, and my knowledge of C is rather limited (Only to 3D printing). I do have a bit of programming experience from QBasic, and I learned about arrays and logic switches later, so I do know some of the arguments that the program uses, and I have learned how to make my own custom text boxes in the game. (Although for the actor logic switches, I figured acrophile was the "floating in air" switch, so there's one of my blunders right there.)

I'm actually better at making the graphics, story, and some of the music for the game idea I have in mind using your reconstruction. It's just that I'm itching to get it done, because it's been in development for almost 14 years. XD Yes, you read that right. I started in 2007, when I found out there were editing tools for the game. Although, my artistic skills since then have amazingly improved.

[smitelli]

Not a problem. I'm happy to point out where things are, or how specific behaviors work. The reconstruction is pretty solid, but the comments are lacking in many respects and I can see how that might make things difficult for somebody who hasn't been looking at it for five years. (That's about how long it took me.)

[smitelli]

I'm going to close this issue since it looks like the root question has been answered. I'll keep #3 open as my reminder to revisit the comments to try to make the code a little clearer.