3D Transition Migration Guide

Since the refactor of the 3D visual architecture, custom 3D transitions are no longer created by inheriting standalone 3D classes (Trainer3D, WildTransition). Instead, all 2D transitions are automatically imported into 3D via Transition3D.from_2d + CameraHandling.

How it works

When the engine loads, every 2D transition registered in WILD_TRANSITIONS / TRAINER_TRANSITIONS is automatically wrapped into a 3D-compatible class:

Visual::WILD_TRANSITIONS.each do |id, klass|
  next if WILD_TRANSITIONS_3D.key?(id)

  WILD_TRANSITIONS_3D[id] = Transition3D.from_2d(klass)
end

Transition3D.from_2d(klass) creates an anonymous class that inherits your 2D transition and includes CameraHandling, which overrides sprite setup, camera movements, shader effects and ball throw sequences.

Creating a custom transition

Step 1 - Write the 2D transition

Create your transition class inheriting from Battle::Visual::Transition::Base or any existing transition, then register it:

module Battle
  class Visual
    module Transition
      class MyCustomWild < Base
        # Override create_all_sprites, create_pre_transition_animation,
        # create_fade_in_animation, create_sprite_move_animation, etc.
      end
    end

    WILD_TRANSITIONS[42] = Transition::MyCustomWild
    # Optional: register a resource type (:sprite, :artwork_full, :artwork_small)
    Visual.register_transition_resource(42, :artwork_full)
  end
end

Step 2 - There is no step 2

The 2D transition is automatically imported into 3D. CameraHandling takes care of:

  • Camera positioning at battle start (setup_camera_position)
  • Sprite shader color animations (create_sprite_shader_animations)
  • Camera movement during sprite reveal (create_sprite_move_animation)
  • Fade out reset (create_fade_out_animation)
  • Player send dezoom/reset camera (dezoom_camera_animation, reset_camera_animation)
  • Ball throw sequences for 1v1, 2v2, 3v3 and multi (ball_throw_player)
  • Enemy send and battle end animations
  • Follower handling (setup_followers_3d)

The resource type is also mirrored automatically.

Overriding 3D behavior for a specific transition

If you need custom 3D behavior that CameraHandling doesn't cover, register your class directly in the 3D hash before the auto-import runs (i.e. in a file loaded before 501 Transition3D.rb):

module Battle
  class Visual3D
    module Transition3D
      class MyCustom3DWild < Battle::Visual::Transition::MyCustomWild
        include CameraHandling

        def initialize(scene, screenshot, camera, camera_positionner)
          super(scene, screenshot)
          @camera = camera
          @camera_positionner = camera_positionner
          setup_camera_position
        end

        # Override only the 3D-specific methods you need
        def create_sprite_move_animation
          # Custom camera work here
        end
      end
    end

    # Register before auto-import so it won't be overwritten
    WILD_TRANSITIONS_3D[42] = Transition3D::MyCustom3DWild
  end
end

The auto-import skips IDs already present in the 3D hash (next if WILD_TRANSITIONS_3D.key?(id)).

Monkey-patching a specific imported transition

Since from_2d creates anonymous classes, you cannot reference them by name. Use the hash instead:

module MyCameraOverride
  def create_sprite_move_animation
    # Custom behavior
    super
  end
end

# Patch the 3D version of wild transition ID 0
Battle::Visual3D::WILD_TRANSITIONS_3D[0].prepend(MyCameraOverride)

Deleted classes

The following classes no longer exist:

  • Battle::Visual3D::Transition3D::Trainer3D (was in 502 Trainer3D.rb)
  • Battle::Visual3D::Transition3D::WildTransition (was in 503 Wild3D.rb)
  • Battle::Visual3D::Transition3D::RBYTrainer (was in 501 Transition3D.rb)

Any prepend or inheritance targeting these classes will raise NameError.