The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Games-EternalLands-Loader-0.03
River stage zero No dependents
++
/ Games::EternalLands::Loader

NAME

Games::EternalLands::Loader - Access Eternal Lands content files

SYNOPSIS

    use Games::EternalLands::Loader;

    my $loader = Games::EternalLands::Loader->new;
    $loader->content_path('/usr/share/games/eternal-lands');
    
    use Data::Dumper;

    my $map = $loader->load('maps/startmap.elm');
    print Dumper($map);

    my $entity = $loader->load('3dobjects/bag1.e3d');
    print Dumper($entity);

    ...

ABSTRACT

This module reads binary content files for the online game Eternal Lands and unpacks them into perl data structures.

METHODS

new

Creates a new Games::EternalLands::Loader object.

content_path

Sets the directory where the content files are located. The argument may be a string to set a single path, or an array reference to set multiple paths to be used in turn. If no argument is given the current value (an array reference) is returned.

load

load NAME

Finds, opens, reads and constructs the game asset identified by the given name.

In case there is some error opening the file or parsing its contents, undef is returned. A description of the error can be retrieved using the "errstr" method.

See "DATA STRUCTURES" for what exactly is returned in each case.

errstr

Returns a string describing the last error that occurred.

DATA STRUCTURES

The returned value from "load" is a hash reference with the following data in each case.

Maps

The maps used by Eternal Lands are tile-based with each 6x6 square of tiles grouped into one terrain square. Each tile has side length 0.5 units in world coordinates. Thus each terrain square has an area in world coordinates of 3 * 3 = 9 square units. A tile represents the smallest unit of space that a dynamic entity (e.g. a player or a creature) can occupy.

Maps returned by "load" have at least the following fields:

name

The argument passed to load that resulted in this map.

indoors

A boolean flag indicating whether this is map represents a location inside a building, cave, etc., or outside.

ambient_light

A 3 element array containing floating-point RGB values.

terrain_length

Number of terrain squares in the first linear dimension of the map (corresponding to the world x-axis).

terrain_breadth

Number of terrain squares in the second linear dimension of the map (corresponding to the world y-axis).

terrain_count

Total number of terrain squares on the map.

terrain_map

A one-dimensional array containing the terrain number for each terrain coordinate. It contains exactly terrain_count elements. Given a terrain coordinate pair ($tx, $ty), the terrain at that location is

  $num = $map->{terrain_map}->[$map->{terrain_length} * $ty + $tx];

The terrain number maps to a texture asset name as

  $tex = "3dobjects/tile$num." . $extension;

where $extension is an image file extension (usually "dds").

NOTE: Terrain number 0 and all numbers between 230 and 255 (not inclusive) are treated as "water" and are drawn at z = -0.25 in world coordinates (rather than at z = 0 like all other terrain squares).

Terrain 255 is the "empty terrain" (a.k.a. "null") and is not drawn at all.

If the map is an indoor map then terrain number 0 is replaced by 231 every time it occurs.

Some maps will refer to missing terrain textures; these are simply ignored rather than being a fatal error. Depending on your application you may wish to notify the user with a warning.

tile_length

Number of tiles in the first linear dimension of the map (corresponding to the world x-axis).

tile_breadth

Number of tiles in the second linear dimension of the map (corresponding to the world y-axis).

tile_count

Total number of tiles on the map.

tile_map

An array of length tile_count containing an integer height value for each tile. Given tile coordinates ($x, $y), the corresponding height is found using

  $h = $map->{tile_map}->[$map->{tile_length} * $y + $x];

A value of zero indicates that the tile is impassable. Otherwise the value maps to a coordinate along the world z-axis as

  $z = $h * 0.2 - 2.2;

NOTE: When drawing the map the tile's height value affects only where dynamic entities such as players, bags, etc. are drawn; terrain squares are always drawn at z = 0 in world space (except for water terrains, which are drawn at z = -0.25).

mesh_objects

An array of hashes each containing at least the fields:

entity_name - Entity this object is an instance of.
id - Numeric identifier for this object.
position - 3-element array containing world coordinates.
rotation - 3-element array containing degree rotations about each axis.
scale - Scaling factor for all three dimensions.
quad_objects

An array of hashes each containing at least the fields:

entity_name - Entity this object is an instance of.
id - Numeric identifier for this object.
position - 3-element array containing world coordinates.
rotation - 3-element array containing degree rotations about each axis.
light_objects

An array of hashes each containing at least the fields:

position - 3-element array containing world coordinates.
color - Floating-point RGB vector.
fuzz_objects

An array of hashes representing particle systems each containing at least the fields:

entity_name - Entity this object is an instance of.
position - 3-element array containing world coordinates.

Mesh Entities

Static 3D objects on the map are represented using triangular face-vertex meshes. Each mesh is further subdivided into a small number of submeshes each with its own texture (or two textures in some cases).

vertices

An array of hashes each containing:

position - 3-element array containing the world coordinates of this vertex.
uv - 2-element array containing texture coordinates.
uv2 - 2-element array containing secondary texture coordinates (OPTIONAL).
normal - 3-element array representing the normal vector for this vertex (OPTIONAL).
tangent - 3-element array representing the tangent vector for this vertex (OPTIONAL).
color - 4-element floating-point RGBA color vector (OPTIONAL).

NOTE: Some fields may not appear, but for any given mesh all vertices will have the same fields present.

indices

An array containing indices into the vertices array for each triangular face. So the first three elements correspond to the three vertices making up the first triangle, the second three the second triangle, and so on.

submeshes

An array of hashes each containing at least:

texture_name - Image file containing the texture applied to this submesh. NOTE: It is given relative to the full path of the entity, without the leading content sub-directories.
minimum_vertex_index - The smallest index into the vertices array of any vertex in this submesh.
maximum_vertex_index - The largest index into the vertices array of any vertex in this submesh.
index_element_count - The number of elements of the indices array used by this submesh.
index_element_offset - Where this submesh starts in the indices array.
texture2_name - Name of the secondary texture (OPTIONAL).

Quad Entities

These are static rectangular map objects generally used for ground details. For consistency with "Mesh Entities" their geometric data is also given in a triangular face-vertex format, albeit without submeshes.

texture_name - Image file containing the texture applied to this submesh. NOTE: It is given relative to the full path of the entity, without the leading content sub-directories.
vertices - Array of hashes each containing fields position, uv and normal.
indices - Array of integers giving the vertices in each triangle face.

AUTHOR

Cole Minor, <coleminor at hush.ai>

LICENSE AND COPYRIGHT

Copyright (C) 2012 Cole Minor. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.