core: Clarify behavior on duplicate character IDs

Author: moulins

core/src/display_object/movie_clip.rs

@@ -3606,10 +3606,15 @@ impl<'gc, 'a> MovieClipShared<'gc> {
             num_frames,
         );
 
-        self.library_mut(context)
-            .register_character(id, Character::MovieClip(movie_clip));
-
-        self.preload_progress.cur_preload_symbol.set(Some(id));
+        if self.library_mut(context)
+            .register_character(id, Character::MovieClip(movie_clip))
+        {
+            self.preload_progress.cur_preload_symbol.set(Some(id));
+        } else {
+            // This character was already defined, so we can skip preloading it, as the
+            // character ID refers to the pre-existing character, and not this one.
+            return Ok(ControlFlow::Exit);
+        }
 
         let should_exit = chunk_limit.did_ops_breach_limit(context, 4);
         if should_exit {

core/src/library.rs

@@ -142,16 +142,22 @@ impl<'gc> MovieLibrary<'gc> {
         }
     }
 
-    pub fn register_character(&mut self, id: CharacterId, character: Character<'gc>) {
-        // TODO(Herschel): What is the behavior if id already exists?
-        if !self.contains_character(id) {
-            if let Character::Font(font) = character {
-                self.fonts.register(font);
+    /// Registers a character; returns `true` if successful, or `false` if a character with
+    /// the given ID already exists.
+    pub fn register_character(&mut self, id: CharacterId, character: Character<'gc>) -> bool {
+        use std::collections::hash_map::Entry;
+        match self.characters.entry(id) {
+            Entry::Vacant(e) => {
+                if let Character::Font(font) = character {
+                    self.fonts.register(font);
+                }
+                e.insert(character);
+                true
+            }
+            Entry::Occupied(_) => {
+                tracing::error!("Character ID collision: Tried to register ID {} twice", id);
+                false
             }
-
-            self.characters.insert(id, character);
-        } else {
-            tracing::error!("Character ID collision: Tried to register ID {} twice", id);
         }
     }