Fifengine - Manual

engine = fife.Engine()
engine.init()

# Initialize engine pumping
engine.initializePumping()

# Main game loop
running = True
while running:
    engine.pump()  # Process one frame
    # Update game logic here

# Clean up
engine.finalizePumping()
engine.destroy()

sound_manager = engine.getSoundManager()
event_manager = engine.getEventManager()
time_manager = engine.getTimeManager()
model = engine.getModel()
vfs = engine.getVFS()
render_backend = engine.getRenderBackend()
gui_manager = engine.getGuiManager()

settings = engine.getSettings()

# Screen dimensions
settings.setScreenWidth(1024)
settings.setScreenHeight(768)

# Display mode
settings.setFullScreen(True)
settings.setBitsPerPixel(32)
settings.setVSync(True)
settings.setRefreshRate(60)

# Render backend
settings.setRenderBackend("OpenGL")  # or "SDL"

settings.setWindowTitle("My Game")
settings.setWindowIcon("icon.png")

settings.setInitialVolume(0.8)  # 80% volume

# Texture filtering
settings.setGLTextureFiltering("nearest")  # or "linear"

# Texture compression
settings.setGLCompressImages(True)

# Mipmapping
settings.setGLUseMipmapping(True)

# Framebuffer effects
settings.setGLUseFramebuffer(True)

settings.setDisplay(0)  # Primary display (default)
settings.setDisplay(1)  # Secondary display

settings.setSDLDriver("software")  # Platform-dependent values

settings.setVideoDriver("x11")  # Linux X11

settings.setColorKeyEnabled(True)
settings.setColorKey(255, 0, 255)  # Magenta as transparent color

settings.setGLUseMonochrome(True)

settings.setGLUseDepthBuffer(True)
settings.setGLAlphaTestValue(0.1)  # Discard fragments with alpha < 0.1

settings.setSDLRemoveFakeAlpha(True)

settings.setJoystickSupport(True)  # Enable gamepad support

settings.setFrameLimitEnabled(True)
settings.setFrameLimit(60)  # 60 FPS max
if settings.isFrameLimitEnabled():
    print("Frame limit:", settings.getFrameLimit())

settings.setMouseSensitivity(1.5)       # Speed factor (1.0 = default)
settings.setMouseAccelerationEnabled(True)  # Enable mouse acceleration

settings.setNativeImageCursorEnabled(True)
if settings.isNativeImageCursorEnabled():
    print("Using native cursor")

# Create a model coordinate at cell (5, 3, 0)
coord = fife.ModelCoordinate(5, 3, 0)

# Access components
print(coord.x)  # 5
print(coord.y)  # 3
print(coord.z)  # 0

# Create an exact coordinate at (5.5, 3.7, 0.0)
coord = fife.ExactModelCoordinate(5.5, 3.7, 0.0)

# Access components
print(coord.x)  # 5.5
print(coord.y)  # 3.7
print(coord.z)  # 0.0

# Create a location on a layer
location = fife.Location(layer)

# Set position using layer coordinates (cell precision)
location.setLayerCoordinates(fife.ModelCoordinate(5, 3, 0))

# Set position using exact layer coordinates (precise)
location.setExactLayerCoordinates(fife.ExactModelCoordinate(5.5, 3.7, 0.0))

# Get the layer this location is on
layer = location.getLayer()

# Get exact layer coordinates
exact_coords = location.getExactLayerCoordinates()
print(f"Exact: ({exact_coords.x}, {exact_coords.y}, {exact_coords.z})")

# Get cell precision coordinates
cell_coords = location.getLayerCoordinates()
print(f"Cell: ({cell_coords.x}, {cell_coords.y}, {cell_coords.z})")

# Get map coordinates
map_coords = location.getMapCoordinates()
print(f"Map: ({map_coords.x}, {map_coords.y}, {map_coords.z})")

# Get exact coordinates mapped to a specific layer
other_exact = location.getExactLayerCoordinates(target_layer)

# Get cell coordinates mapped to a specific layer
other_cell = location.getLayerCoordinates(target_layer)

offset = location.getCellOffsetDistance()
# Returns distance between exact position and cell center

if location.isValid():
    # Location is ready to use
    pass

# Distance in map coordinates
map_distance = location.getMapDistanceTo(other_location)

# Distance in layer coordinates
layer_distance = location.getLayerDistanceTo(other_location)

# Convert map coordinates to screen coordinates
screen_point = camera.toScreenCoordinates(exact_map_coords)

# Convert screen coordinates back to map coordinates
map_point = camera.toMapCoordinates(screen_point)

# Convert map to virtual screen coordinates (sub-pixel precision)
virtual_screen = camera.toVirtualScreenCoordinates(exact_map_coords)

# Map to virtual screen
virtual = camera.toVirtualScreenCoordinates(map_coords)

# Virtual screen to screen
screen = camera.virtualScreenToScreen(virtual)

# Screen to virtual screen
virtual = camera.screenToVirtualScreen(screen)

def onMousePress(self, event):
    # Get screen coordinates from mouse event
    screen_point = fife.ScreenPoint(event.getX(), event.getY(), 0)

    # Convert to map coordinates
    map_point = camera.toMapCoordinates(screen_point)

    # Convert to layer coordinates for a specific layer
    # (map coordinates are layer-independent)

def move_instance(instance, target_x, target_y):
    # Get current location
    current = instance.getLocation()

    # Create target coordinates
    target = fife.ExactModelCoordinate(target_x, target_y, 0)

    # Create new location on same layer
    new_location = fife.Location(current.getLayer())
    new_location.setExactLayerCoordinates(target)

    # Move the instance
    instance.setLocation(new_location)

def get_instance_at(screen_x, screen_y, camera, layer):
    # Convert screen coordinates to screen point
    screen_point = fife.ScreenPoint(screen_x, screen_y, 0)

    # Get matching instances
    instances = []
    camera.getMatchingInstances(screen_point, layer, instances)

    return instances[0] if instances else None

def place_object_at(object_id, layer, cell_x, cell_y):
    # Create location at specific cell
    location = fife.Location(layer)
    location.setLayerCoordinates(fife.ModelCoordinate(cell_x, cell_y, 0))

    # Create instance
    instance = layer.createInstance(object_id, location)
    return instance

p = fife.Point(3, 4)

# Vector operations
p2 = p + fife.Point(1, 2)   # (4, 6)
p3 = p - fife.Point(1, 1)   # (2, 3)
p4 = p * 2                   # (6, 8)
p5 = p / 2                   # (1, 2)

# Length (magnitude)
length = p.length()  # 5.0

# Normalize to unit vector
p.normalize()

# Rotate around origin (degrees)
p.rotate(90)

# Rotate around a specific point
origin = fife.Point(0, 0)
p.rotate(origin, 45)

# Set coordinates
p.set(10, 20)

p = fife.Point3D(1, 2, 3)

# Same operations as Point2D, plus z-component
length = p.length()
p.normalize()
p.set(10, 20, 30)

# Double to int (rounds)
int_point = fife.doublePt2intPt(double_point)

# Int to double
double_point = fife.intPt2doublePt(int_point)

<?xml version="1.0" encoding="utf-8"?>
<fife version="0.4.0">
  <map id="mymap">
    <name>My Map</name>
    <grid type="square">
      <cell_scale>1.0</cell_scale>
      <x_scale>1.0</x_scale>
      <y_scale>1.0</y_scale>
      <rot>0</rot>
      <tilt>0</tilt>
      <x_offset>0</x_offset>
      <y_offset>0</y_offset>
    </grid>
    <elevation id="el1">
      <name>Ground Floor</name>
      <layer id="layer1">
        <name>Ground Layer</name>
        <grid type="square">
          <cell_scale>1.0</cell_scale>
          <x_scale>1.0</x_scale>
          <y_scale>1.0</y_scale>
          <rot>0</rot>
          <tilt>30</tilt>
        </grid>
        <instances>
          <instance object="myobject" x="0" y="0" id="inst1"/>
        </instances>
      </layer>
    </elevation>
  </map>
</fife>

<instance object="tree" x="5" y="3" id="tree1"/>
<instance object="building" x="10" y="7" id="building1" rotation="90"/>

lightrenderer.setBlendMode(
    src_factor="src_alpha",
    dst_factor="one"  # Additive blending
)

lightrenderer.setGroupIndex(my_group_index)
lightrenderer.addSimpleLightInfo(...)

settings = engine.getSettings()
settings.setRenderBackend("OpenGL")  # or "SDL"

settings = engine.getSettings()
settings.setScreenWidth(1024)
settings.setScreenHeight(768)
settings.setBitsPerPixel(32)
settings.setFullScreen(True)
settings.setVSync(True)

# Texture filtering (improves image quality)
settings.setGLTextureFiltering("linear")  # none, linear, bilinear, trilinear, anisotropic

# Mipmapping (reduces aliasing at distance)
settings.setGLUseMipmapping(True)

# Texture compression (reduces memory usage)
settings.setGLCompressImages(True)

# Framebuffer effects (for post-processing)
settings.setGLUseFramebuffer(True)

# NPOT textures (non-power-of-two sizes)
settings.setGLUseNPOT(True)

# Depth buffer (for 3D effects)
settings.setGLUseDepthBuffer(True)

import fifengine

# Get the map
map = model.getMap("mymap")

# Define viewport (area of screen to render to)
viewport = fifengine.Rect(0, 0, 800, 600)

# Create camera
camera = fifengine.Camera("mycam", map, viewport, engine.getRenderBackend())

# Create a location
location = fifife.Location(layer)
location.setLayerCoordinates(fife.ModelCoordinate(10, 10, 0))

# Move camera to location
camera.setLocation(location)

# Attach to instance
camera.attach(instance)

# Detach
camera.detach()

# Map to screen
screen_point = camera.toScreenCoordinates(map_coords)

# Screen to map
map_point = camera.toMapCoordinates(screen_point)

# Virtual screen coordinates (sub-pixel precision)
virtual = camera.toVirtualScreenCoordinates(map_coords)

# Convert between virtual and screen
screen = camera.virtualScreenToScreen(virtual)
virtual = camera.screenToVirtualScreen(screen_point)

camera.setPosition(fife.ExactModelCoordinate(10.5, 20.3))
pos = camera.getPosition()

camera.setEnabled(False)  # Disable rendering
camera.setEnabled(True)   # Enable rendering

camera.setZToY(32)             # 1 z-unit = 32 pixels vertically
camera.setZToYEnabled(True)    # Enable custom z-to-y
camera.setZToYEnabled(False)   # Use original matrix value
is_enabled = camera.isZToYEnabled()
original = camera.getOriginalZToY()  # Original value from matrix

camera.setCellImageDimensions(64, 32)
dims = camera.getCellImageDimensions()        # For current layer
dims = camera.getCellImageDimensions(layer)   # For specific layer

# Reference scale factors
scale_x = camera.getReferenceScaleX()
scale_y = camera.getReferenceScaleY()

# Single point hit test
instances = []
camera.getMatchingInstances(
    fife.ScreenPoint(x, y, 0), layer, instances, alpha=0
)

# Rectangle selection
rect = fife.Rect(x, y, width, height)
instances = []
camera.getMatchingInstances(rect, layer, instances, alpha=128)

# Location-based matching (sorted by camera view)
location = fife.Location(layer)
location.setLayerCoordinates(fife.ModelCoordinate(5, 3))
instances = []
camera.getMatchingInstances(location, instances)

# Set lighting color (RGB floats 0.0-1.0)
camera.setLightingColor(0.5, 0.5, 1.0)  # Blue tint

# Get current lighting
color = camera.getLightingColor()  # Returns [r, g, b]

# Reset to default
camera.resetLightingColor()

# Color overlay (RGBA)
camera.setOverlayColor(255, 0, 0, 128)  # Semi-transparent red
color = camera.getOverlayColor()
camera.resetOverlayColor()

# Image overlay
camera.setOverlayImage(image_id, fill=True)  # Fill viewport
img_id = camera.getOverlayImage()
camera.resetOverlayImage()

# Animation overlay
camera.setOverlayAnimation(anim_ptr, fill=True)
anim = camera.getOverlayAnimation()
camera.resetOverlayAnimation()

camera.resetRenderers()

# Set viewport
camera.setViewPort(fife.Rect(100, 50, 600, 400))

# Get viewport
viewport = camera.getViewPort()

instance_renderer = camera.getRenderer("InstanceRenderer")
light_renderer = camera.getRenderer("LightRenderer")
grid_renderer = camera.getRenderer("GridRenderer")

renderer = camera.getRenderer("GridRenderer")
renderer.setEnabled(True)   # Enable
renderer.setEnabled(False)  # Disable

renderer.setPipelinePosition(5)  # Render 5th in pipeline

renderer.addActiveLayer(my_layer)      # Add one layer
renderer.clearActiveLayers()           # Clear all
renderer.activateAllLayers(my_map)     # Activate all from map

renderer = camera.getRenderer("InstanceRenderer")

renderer = camera.getRenderer("GridRenderer")
renderer.setEnabled(True)

lightrenderer = camera.getRenderer("LightRenderer")

# Add simple light
lightrenderer.addSimpleLightInfo(
    layer=layer,
    x=5, y=5,
    color=[255, 255, 128],
    intensity=200,
    radius=5.0
)

# Add image-based light
lightrenderer.addImageLightInfo(
    layer=layer,
    image="light.png",
    x=5, y=5
)

# Add animated light
lightrenderer.addAnimationLightInfo(
    layer=layer,
    animation="flicker.anim",
    x=5, y=5
)

renderer = camera.getRenderer("GenericRenderer")

rb = engine.getRenderBackend()

# Draw a pixel
rb.putPixel(x, y, r, g, b, a=255)

# Draw a line
rb.drawLine(fife.Point(x1, y1), fife.Point(x2, y2), r, g, b, a=255)

# Draw a thick line
rb.drawThickLine(fife.Point(x1, y1), fife.Point(x2, y2), width, r, g, b, a=255)

# Draw connected lines
points = [fife.Point(0, 0), fife.Point(10, 10), fife.Point(20, 0)]
rb.drawPolyLine(points, width, r, g, b, a=255)

# Draw bezier curve
rb.drawBezier(points, steps, width, r, g, b, a=255)

# Draw rectangle outline
rb.drawRectangle(fife.Point(x, y), width, height, r, g, b, a=255)

# Draw filled rectangle
rb.fillRectangle(fife.Point(x, y), width, height, r, g, b, a=255)

# Draw circle outline
rb.drawCircle(fife.Point(cx, cy), radius, r, g, b, a=255)

# Draw filled circle
rb.drawFillCircle(fife.Point(cx, cy), radius, r, g, b, a=255)

# Draw circle segment (0 angle is right side)
rb.drawCircleSegment(fife.Point(cx, cy), radius, start_angle, end_angle, r, g, b, a=255)

# Draw filled circle segment
rb.drawFillCircleSegment(fife.Point(cx, cy), radius, start_angle, end_angle, r, g, b, a=255)

# Draw triangle
rb.drawTriangle(fife.Point(x1,y1), fife.Point(x2,y2), fife.Point(x3,y3), r, g, b, a=255)

# Draw quad
rb.drawQuad(p1, p2, p3, p4, r, g, b, a=255)

# Draw vertex point
rb.drawVertex(fife.Point(x, y), size, r, g, b, a=255)

rb.enableScissorTest()
# ... draw clipped content ...
rb.disableScissorTest()

anim = fife.Animation()

# Add frames with durations (in milliseconds)
anim.addFrame(image_ptr_1, 100)  # Show for 100ms
anim.addFrame(image_ptr_2, 100)
anim.addFrame(image_ptr_3, 150)

# Get frame index by timestamp
index = anim.getFrameIndex(timestamp)

# Get frame image by index
frame = anim.getFrame(index)

# Get frame by timestamp
frame = anim.getFrameByTimestamp(timestamp)

# Get all frames
frames = anim.getFrames()

# Get frame duration
duration = anim.getFrameDuration(index)  # milliseconds

# Total frame count
count = anim.getFrameCount()

# Total animation duration
total = anim.getDuration()  # milliseconds

anim.setActionFrame(2)   # Action happens on frame 2
action_frame = anim.getActionFrame()

anim.setDirection(0)      # Default direction
direction = anim.getDirection()

# From SDL_Surface (takes ownership)
image = fife.Image(surface)

# From raw RGBA pixel data
image = fife.Image(pixel_data, width, height)

# From a resource loader
image = fife.Image("name", loader)

# Basic render with optional alpha
image.render(rect, alpha=255)

# Render with color overlay (RGB bytes)
image.render(rect, alpha=255, rgb=[r, g, b])

# Render with z-depth (OpenGL only)
image.renderZ(rect, vertexZ, alpha=255)

# Render with overlay image and z-depth
image.renderZ(rect, vertexZ, overlay_image, alpha=255)

surface = image.detachSurface()
# Now caller is responsible for freeing the surface

image.setSurface(new_surface)

image.forceLoadInternal()

width = image.getWidth()
height = image.getHeight()
area = image.getArea()  # Returns Rect(0, 0, width, height)

r, g, b, a = image.getPixelRGBA(x, y)

image.setXShift(10)
image.setYShift(-5)
shift_x = image.getXShift()
shift_y = image.getYShift()

image.saveImage("output.png")

image.useSharedImage(shared_image_ptr, region_rect)
if image.isSharedImage():
    rect = image.getSubImageRect()

target_image.copySubimage(xoffset, yoffset, source_image_ptr)

model = engine.getModel()
my_map = model.createMap("mymap")

# Create a cell grid (square or hex)
grid = fife.SquareGrid()  # or fife.HexGrid()

# Add a layer to the map
layer = my_map.createLayer("ground_layer", grid)

# Get existing layers
layers = my_map.getLayers()
ground = my_map.getLayer("ground_layer")

# Add camera to map
camera = my_map.addCamera("main_camera", viewport)

# Get camera
camera = my_map.getCamera("main_camera")

# Get all cameras
cameras = my_map.getCameras()

# Check if map changed
if my_map.isChanged():
    changed_layers = my_map.getChangedLayers()

my_map.setTimeMultiplier(1.0)   # Normal speed
my_map.setTimeMultiplier(2.0)   # Double speed
my_map.setTimeMultiplier(0.5)   # Half speed

time_provider = my_map.getTimeProvider()
game_time = time_provider.getGameTime()

count = my_map.getLayerCount()
my_map.deleteLayers()  # Remove all layers

min_coord, max_coord = my_map.getMinMaxCoordinates()

my_map.setFilename("saves/mymap.sav")
filename = my_map.getFilename()

count = my_map.getActiveCameraCount()

# Register instance for transfer
my_map.addInstanceForTransfer(instance)

# Unregister
my_map.removeInstanceForTransfer(instance)

# Initialize cell caches after all transfers
my_map.initializeCellCaches()

# Clean up cell caches
my_map.finalizeCellCaches()

trigger_ctrl = my_map.getTriggerController()

# Create instance at exact position
instance = layer.createInstance(my_object, fife.ModelCoordinate(5, 3), "my_instance")

# Create instance at precise position
instance = layer.createInstance(my_object, fife.ExactModelCoordinate(5.5, 3.2), "precise")

# Get all instances
instances = layer.getInstances()

# Get instance by ID
instance = layer.getInstance("my_instance")

# Get instances by type
instances = layer.getInstances("tree")

# Get instances at location
location = fife.Location(layer)
location.setLayerCoordinates(fife.ModelCoordinate(5, 3))
instances_at = layer.getInstancesAt(location)

# Get instances in rectangle
rect = fife.Rect(0, 0, 10, 10)
instances_in = layer.getInstancesIn(rect)

# Get instances in circle
instances = layer.getInstancesInCircle(fife.ModelCoordinate(5, 5), 3)

# Get instances in line
instances = layer.getInstancesInLine(
    fife.ModelCoordinate(0, 0),
    fife.ModelCoordinate(10, 10)
)

layer.removeInstance(instance)  # Remove without deleting
layer.deleteInstance(instance)  # Remove and delete

# Create with a master provider (or None for root)
provider = fife.TimeProvider(master_provider)

# Set local multiplier (0.5 = half speed, 2.0 = double speed)
provider.setMultiplier(2.0)

# Get local multiplier
local = provider.getMultiplier()

# Get total multiplier including all parents
total = provider.getTotalMultiplier()  # E.g., master=2.0, local=0.5 -> 1.0

# Get current scaled game time in milliseconds
game_time = provider.getGameTime()

namespace = object.getNamespace()  # e.g., "vegetation"
object.setId("oak_tree")           # Set object identifier

# Mark object as a multi-part component
object.setMultiPart(True)

# Add part identifiers
object.addMultiPartId("tower_base")
object.addMultiPartId("tower_top")

# Get all part IDs
part_ids = object.getMultiPartIds()

# Set rotation anchor for the multi object
object.setRotationAnchor(fife.ExactModelCoordinate(0.5, 0.5))

# Enable restricted rotation (only use predefined angles)
object.setRestrictedRotation(True)

# Get obvious rotation from any angle
snapped = object.getRestrictedRotation(47)  # Returns nearest valid angle

# Add coordinates for specific rotations
object.addMultiPartCoordinate(0, fife.ModelCoordinate(0, 0))
object.addMultiPartCoordinate(90, fife.ModelCoordinate(1, 0))

# Get coordinates for a rotation
coords = object.getMultiPartCoordinates(90)
all_coords = object.getMultiPartCoordinates()  # All rotations