40250 classic: parallel-dev checkpoint through increment 49 (W0 interface freeze)

Captures the uncommitted parallel-development work (increments 46-49) on the
40250 classic client port, folded into docs/CLIENT-GAP.md + CLIENT-GAP-FIX.md.

Increment 49 (W0 interface-freeze batch, Phase 1 prerequisite) lands the
cross-workflow shared-file scaffolding so the 4 Phase 1 workflows can run in
isolated worktrees without contention:

- entity_store.{h,cpp}: Entity gains empire/affect_flags/owner_vid/state_flags;
  new mut_spawn_full() (single-shot two-packet merge, §2.3), mut_ownership()
  (§2.5), mut_map_bgm() + take_bgm_dirty()/bgm_name()/bgm_volume() (§9.1),
  drain_dirty() (§2.1/§2.5 bare-field-update queue); mut_char_info() now stores
  empire; reset_for_map_change() clears m_dirty.
- m2_client.cpp: new bgm_changed(name, volume) signal; classic + m2dev pump
  loops drain drain_dirty() -> entity_info and take_bgm_dirty() -> bgm_changed;
  entity_dict() exposes the 4 new keys.
- classic/classic_parser.{h,cpp}: GC_MAIN_CHARACTER3_BGM /
  GC_MAIN_CHARACTER4_BGM_VOL route bgm_name/bgm_volume to mut_map_bgm() (was
  discarded); new m_pending_actor staging map (W1 fills §2.2 merge logic).
- project/bgm_director.gd (new) + game_scene.gd: BGM consumption split out of
  net_world.gd so W2/W4 don't collide; §8.6/§4.8 keybind convergence (digits
  1-4 -> quickslots 0-3, F1-F4 -> quickslots 4-7, Ctrl+1..9 -> _emote()).

Tests: cmake --build build clean; ctest 16/16; 15 GDScript regressions green
(netbridge, gamescene, netplay, p9, p10, p2b, p8, system_menu_ui, skill,
combat_fx, skill_fx, player_motion, char_status_ui, chat, inventory), no skips.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014yvAPqPivoY7vmBbzgqK4W

extension/src/net/entity_store.h

@@ -62,16 +62,24 @@ struct Entity {
 	int32_t guild = 0;
 	int16_t alignment = 0;
 	uint8_t pk_mode = 0;
+
+	// --- W0 interface freeze (CLIENT-GAP §2.3/§2.5) ---
+	uint8_t empire = 0;         // 1 Shinsoo, 2 Chunjo, 3 Jinno (GC_CHAR_ADDITIONAL_INFO)
+	uint64_t affect_flags = 0;  // AFF_* bitset carried on the entity (buff icons / aura)
+	uint32_t owner_vid = 0;     // summon / horse owner; 0 = none
+	uint32_t state_flags = 0;   // presentation-layer latch bits (W2 defines the enum)
 };
 
 // --- P9 world systems ----------------------------------------------------
-// GC_WARP — teleport target. same_server() -> just move the player; otherwise
-// the caller must reconnect to addr:port (P10).
+// GC_WARP — teleport target. The m2dev protocol uses addr==0 as an in-place
+// warp; the 40250 classic protocol always reconnects, including when lAddr is
+// zero. `reconnect` records that protocol-specific distinction at parse time.
 struct WarpCue {
 	int32_t x = 0, y = 0;
 	int32_t addr = 0;
 	uint16_t port = 0;
-	bool same_server() const { return addr == 0; }
+	bool reconnect = false;
+	bool same_server() const { return !reconnect && addr == 0; }
 };
 // One atlas/minimap NPC entry (GC_NPC_POSITION).
 struct NPCMark {
@@ -466,6 +474,16 @@ public:
 			uint8_t attack_speed = 0);
 	void mut_spawn_main(uint32_t vid, uint16_t race, const std::string &name, float x, float y,
 			float z);
+	// Full spawn (CLIENT-GAP §2.3): merge every field of `e` into the world in one
+	// shot, keyed by e.vid, so a two-packet PC/NPC add (GC_CHARACTER_ADD +
+	// GC_CHAR_ADDITIONAL_INFO) lands as a single Spawn change with name/parts/
+	// empire/affect_flags/owner already populated. Creates the entity if new.
+	void mut_spawn_full(const Entity &e);
+	// summon / horse ownership (CLIENT-GAP §2.5); no-op if vid unknown.
+	void mut_ownership(uint32_t vid, uint32_t owner_vid);
+	// Map background music (CLIENT-GAP §9.1). name is the resolved track id or
+	// path; volume < 0 means "server did not specify, keep current".
+	void mut_map_bgm(const std::string &name, float volume);
 	void mut_despawn(uint32_t vid);
 	// angle_deg is the already-decoded compass heading (m2dev: rot*360/256;
 	// classic: rot*5 — the two wire encodings differ, so decode at the parser).
@@ -554,7 +572,12 @@ public:
 			int32_t counter_value, const std::string &icon);
 
 	// --- P9 world systems ---
-	void mut_warp(int32_t x, int32_t y, int32_t addr, uint16_t port);
+	void mut_warp(int32_t x, int32_t y, int32_t addr, uint16_t port,
+			bool reconnect = false);
+	// Clear the loading-phase state that ClientVS22 resets before a new map
+	// connection. Persistent account data (friends, guild, quests, inventory)
+	// is retained; entities and map-local/transient state are discarded.
+	void reset_for_map_change();
 	void mut_server_time(int64_t time);
 	void mut_channel(uint8_t channel);
 	void mut_npc_marks(const std::vector<NPCMark> &marks);
@@ -968,6 +991,22 @@ public:
 		m_changes.clear();
 		return v;
 	}
+	// vids whose entity fields changed without a Spawn/Move/Info change since the
+	// last drain (deduped). W2 uses this for the §2.1 visibility pass so a bare
+	// ownership/affect update still re-mirrors the node.
+	std::vector<uint32_t> drain_dirty() {
+		auto v = std::move(m_dirty);
+		m_dirty.clear();
+		return v;
+	}
+	// Map BGM (§9.1). Returns true once after mut_map_bgm and consumes the flag.
+	bool take_bgm_dirty() {
+		bool d = m_bgm_dirty;
+		m_bgm_dirty = false;
+		return d;
+	}
+	const std::string &bgm_name() const { return m_bgm_name; }
+	float bgm_volume() const { return m_bgm_volume; }
 	std::vector<ChatMsg> drain_chat() {
 		auto v = std::move(m_chat);
 		m_chat.clear();
@@ -1063,6 +1102,10 @@ private:
 	uint32_t m_main_vid = 0;
 	uint32_t m_now = 0;
 	std::vector<Change> m_changes;
+	std::vector<uint32_t> m_dirty;
+	std::string m_bgm_name;
+	float m_bgm_volume = -1.0f;
+	bool m_bgm_dirty = false;
 	std::vector<ChatMsg> m_chat;
 	std::vector<uint32_t> m_vitals;
 	std::vector<DamageEvent> m_damage;