Maplestory Character Loader v1.0.3

This node pulls your actual MapleStory character - the real in-game one, with its true name, level, world, guild, and equipped look - renders it on Nexon's own servers, and drops it into your ComfyUI graph as a clean cutout with a mask. Not an "in the style of MapleStory" diffusion generation. The actual character, as Nexon draws it today. If you've ever wanted to img2img your main into fan art, feed a sprite to ControlNet, or just composite your own avatar onto things, this is the fastest door in.

Worth one frame of context before we dive in: this node does call an API and does need a key, but it's not the API-wrapper deal most of this ecosystem warns about. It's not a pay-per-call cloud model, no prepaid credits, no subscription. The key is free and the thing you're pulling is your own game data and a sprite. The "API nodes are a resented default" argument mostly doesn't apply here - there is no local way to get your character's current appearance, so calling out is the whole point.

How it works

Three calls under the hood, all hardcoded to the official open.api.nexon.com endpoint (the source is short enough to read in one sitting, and that's a nice security signal for a small pack):

1. Resolve the character name to an ocid (Nexon's internal ID) via /maplestory/v1/id.
2. Fetch the basic info - name, world, level, guild, and the character_image sprite URL - via /maplestory/v1/character/basic.
3. Rebuild the sprite URL with the action/emotion/weapon-motion query params, download the image, and convert it into a ComfyUI IMAGE tensor plus an alpha-derived MASK.

The sprite URL trick is the clever part. Nexon lets you tack query params onto the look endpoint to change the pose - action (A00–A41: stand, walk, every weapon swing and stab animation), emotion (E00–E24: wink, smile, cry, dizzy), and wmotion (W00–W04: one-hand, two-hand, gun, no weapon). You don't build those URLs by hand; the node gives you dropdowns.

Inputs that matter

• api_key - your Nexon Open API key. Free from Nexon's developer portal; paste it into the node. It goes in the x-nxopen-api-key header, same as the README's curl examples.
• character_name - the exact in-game name. This is a Korean game and the name is a Korean string; a typo or a partial name just fails the ocid lookup.
• action / emotion / wmotion dropdowns, plus action_frame and emotion_frame INTs. The frames pick a frame of the animation (most actions only have frames 0–3, and the node won't stop you from asking for one that doesn't exist - the per-action ranges are in the README).
• flip_horizontal and background_color - Comfy-side conveniences. Flip mirrors the sprite; background swaps the default transparency for white, black, gray, or a pastel.
• date (optional) - leave it empty. More on that below.

Outputs

• character_image (IMAGE) and mask (MASK) - the sprite as an RGBA cutout with the alpha channel handed to you as a mask. That's the pair that saves you a background-removal pass: a sprite that's ready to composite, inpaint, or feed to a detailer out of the box.
• character_name, world_name, character_level (INT), character_guild_name (strings) - metadata you can thread into a text prompt or a caption, which is a nice touch for batch naming.

Install

It's a one-node pack with no models and no heavy deps (requests, torch, numpy, Pillow - all already in any stock ComfyUI). ComfyUI Manager: search ComfyUI-Maplestory. Or the manual way:

cd ComfyUI/custom_nodes
git clone https://github.com/JKH-ML/ComfyUI-Maplestory

Restart ComfyUI and the node shows up under the Maplestory category.

Where people get burned

The README's own warning, so take it literally: inputting today's date errors out with OPENAPI00004: Please input valid parameter, because the data lags a day in KST. Leave the date blank, or use an earlier date in YYYY-MM-DD.

Beyond that: characters whose look info is set to private come back with no image, and the node silently falls back to a blank 64×64 tensor - you'll see a black box and wonder. And keep your key out of shared workflow exports; it's sitting right there in the node as plaintext. This pack only ever talks to Nexon's official API, which is exactly what you want from a fan node - but that key is yours, so don't broadcast it.