Custom pickup skill objects

[namida]

Please note that all images in this tutorial have been scaled up to 4x their actual size, and given a magenta (rather than transparent) background. This is for the purpose of clarity in the tutorial; and you should not 4x scale + magenta background the actual image files in your objects.

Finally, it is assumed that you're already familiar with custom objects in general, including the use of secondary animations. If not, please refer to the general information on style formats.

If you prefer to learn from examples than from reading a tutorial: Please look at of course default_pickup (you can more or less ignore the COLOR lines, they're there for the recoloring-in-different-themes feature that custom skills won't generally need), and there are also examples in namida_bridge, namida_basement and namida_garden - these examples don't do the recoloring, but do have other somewhat fancy effects.

First - why are custom pickup skill objects special, compared to any other object? It's because they need to have a graphic of the respective skill on them. Prior to NL 12.7.0, this meant that if any new skill was added - or even simply if the order of them were changed - NeoLemmix might display the wrong skill, or even crash, unless the pickup skill object had been updated to account for the change. Many pickup skill objects never got updated at all; while those that did generally lagged quite far behind the updates to NL themself.

To avoid this problem, custom pickup skill objects are implemented in a somewhat unique way, that removes the need for these kind of updates.



Here's an example of a custom pickup skill object, along with an explanation of how it works. Note that in many cases, you'll be able to use this as almost an exact copy-paste with your custom graphics substituted in (and maybe some tweaks to the primary animation's offsets and/or the trigger area).

Code (pickup.nxmo) Select Expand

EFFECT PICKUPSKILL
TRIGGER_X 4
TRIGGER_Y 9
TRIGGER_WIDTH 4
TRIGGER_HEIGHT 7

DIGIT_X 11
DIGIT_Y 8
DIGIT_ALIGNMENT RIGHT
DIGIT_LENGTH 0

$PRIMARY_ANIMATION
  NAME *PICKUP
  OFFSET_X -6
  OFFSET_Y -6
$END

$ANIMATION
  FRAMES 2
  NAME skill_mask
  HIDE
$END

$ANIMATION
  FRAMES 1
  NAME active
 
  $TRIGGER
    CONDITION EXHAUSTED
    HIDE
  $END
$END

$ANIMATION
  FRAMES 1
  NAME inactive
  HIDE
 
  $TRIGGER
    CONDITION EXHAUSTED
    # "Don't hide" is implied.
  $END
$END

pickup_skill_mask.png

pickup_active.png

pickup_inactive.png

Note that we have not supplied any image for the primary animation, nor any that contain the actual skill icons. These get generated automatically by NeoLemmix.

So, what does this combination of NXMO files and images actually do?

Just to clarify - the stuff at the top is just normal trigger area / effect data. If you don't understand how that works, please review the basics of custom objects.

First of all, let's talk about the "active" and "inactive" secondary animations, because they're the easiest ones to explain. There is nothing special whatsoever about these compared to any other secondary animation. The only thing that's of interest here is the particular effect being created with them - we've got one that's hidden when the pickup skill is not "exhausted", and one that's hidden when the pickup skill is "exhausted". This is in no way unique to pickup skills though - you can use this exact same setup on any object (provided "exhausted" has some meaning for that kind of object).

By specifying the name "*PICKUP"  for the primary animation, this tells NeoLemmix "don't try to load a file; auto-generate a primary animation for a pickup skill". Specifically, this is the animation it will generate:

Pickup skill auto-generated primary animation

This primary animation will always be 24x24 in size. For new objects, I recommend designing around that. However, in this case, this looks like a default pickup skill object, and might need compatibility - that's why, instead of moving the trigger area 6px right and 6px down, I've offset the primary animation in the opposite direction. The "OFFSET_X" and "OFFSET_Y" work exactly as normal here.

Note how there are two frames for each skill. The first frame is how the skill will be drawn after it's been picked up; the second is how it will be drawn before it's been picked up. Of course, you probably don't want these to be identical; and chances are you also need them to be cropped to fit your actual skill. Both of these are where the "skill_mask" animation comes into play.

The "skill_mask" animation must always be two vertically-arranged frames, 24x24 in size (per frame, so 24x48 for the whole image). These are used to erase the skill icons - the first frame erases the "picked up" graphic, the second frame erases the "not picked up" graphic. Often, the first frame will be a total erase, while the second will just crop the skill to fit your pickup skill object - but if you can find another way to use them that doesn't mislead the player, try it out!

We don't want this animation itself to actually show up as part of the object, which is why we just configure it as always hidden.

If you do not supply a "skill_mask" animation, NeoLemmix will fully erase the "picked up" frames, and leave the "not picked up" frames as-is, with no cropping / etc. I suspect there will be very few cases where this is visually desirable.

Visual example

Finally, let's look at the "DIGIT" parameters. These specify where to draw the skill count, in the case that the pickup skill object gives more than one skill. The default position, if nothing is specified, is centered above the object with a minimum length of 1 digit. The coordinates provided here instead place it right-aligned, in the bottom-right corner. In the case of pickup skills, if the skill quantity is 1 and the minimum digits length is 0, no number will be displayed. In all cases, no number will be displayed once the skill is picked up.

If you want to use outright custom graphics for your digits, you would supply these as a secondary animation with 10 frames called "DIGITS" that's always hidden, similar to how the "skill_mask" animation is. I do not have an example of this ready to show off.

What if I want my pickup skill object to have a different name? Maybe I want to call it "bob_smith" instead of "pickup"?

You can do this, no problem. "Pickup" as the name of the piece is not special in any way. Of course, you'll need to rename the secondary animations accordingly, just like with any other secondary animations - the piece name, an underscore, and the animation name. In this case, "bob_smith_skill_mask.png", "bob_smith_inactive.png" and "bob_smith_active.png".

Note that the primary animation being given the "NAME *pickup" should not change - "*pickup" itself, as an animation name, is what tells the player to autogenerate it. You do not change this to "NAME *bob_smith".

What about the animations themself, can I change their names?

In this example above, "active" and "inactive" are just names I chose for those animations. There's nothing special about them; you could call them "cat" and "dog" if you wanted to. Indeed, there's nothing special about these animations at all; they're just regular, everyday secondary animations. The only reason attention is drawn to them is to show using secondary animations to produce the active vs inactive backgrounds that we're used to pickup skills having (and indeed, you could do something completely different).

However, "skill_mask" IS a special name. When "*pickup" is encountered and the pickup skill icons are auto-generated, NeoLemmix specifically looks for a secondary animation with the name "skill_mask" to use as the eraser. You cannot call this animation anything else.

Can I just manually provide the primary animation instead, like we've always done, and just update it as needed?

Theoretically, yes, you can. However, this puts you back in the situation of having to update your custom pickup skill object every time NeoLemmix adds a new skill and/or changes the order of skills. Every user so far who has created custom pickup skills has been quite slow to do this after an NL update - or worse, hasn't updated their pickup skills at all.

As such, in practice, the answer is no, you cannot do this. If you create a pickup skill object this way (instead of using the automatic skill generation) and submit it to the styles download, it will be rejected. I may consider making exceptions under two very strict conditions: (a) it must be done to achieve something that's not misleading visually but also cannot be done with the standard pickup skill objects, and (b) it must come from a user who has an excellent track record of keeping their content up to date.

Even if you feel you meet both conditions, discuss it with NL developers first. We might be able to figure out a way we can just tweak the automatic system to suit your use case, rather than introducing a manual-update-reliant pickup skill object.

[namida]

Earlier, for a user on Discord, I put together a "template" custom pickup skill object - this is basically the default one, but without the recoloring-related things that custom pickups generally won't need.

I figured - may as well post it here. Feel free to use this as a starting point for any you're creating. If you're not intending to do anything that wasn't possible before, it should be as simple as:
1. Start with this template.
2. Keeping the canvas size the same, replace the graphic in pickup_inactive.png with the after-picking-up graphic of your object.
3. Again keeping the canvas size the same, replace the graphic in pickup_active.png with the before-picking-up background of your object (ie: with no skill graphic on it).
4. If your pickup skill's shape is quite different, modify pickup_skill_mask.png appropriately. Look at the visual example in the above post, it's probably the best explanation of how this works.
5. Modify trigger areas (and if desired, digit positioning) in the NXMO file.
6. If you want a different name from "pickup", rename all four files, replacing "pickup" at the start with your new name (keep the rest of the name, where applicable, as is).

Even if you want to get fancier than that, this could still be a useful starting point.