/ 
Games-Simutrans-Pakset-0.02
River stage zero No dependents
++
/ Games::Simutrans::Pak

NAME

Games::Simutrans::Pak - Represents a single Simutrans object.

VERSION

version 0.01

SYNOPSIS

  use Games::Simutrans::Pakt;

  my $p = Games::Simutrans::Pak->new;

DESCRIPTION

This module works in concert with Games::Simutrans::Pakset as objects that represent portions of a Pakset for the Simutrans game. These objects have various attributes like Games::Simutrans::Image images (using the Imager module) and are also accompanied by various other meta-information like language translations.

Pak objects created with this module are relatively free-form in what information may be stored, with the to_string method generally making a best-effort to emit scalars and arrays in a format that should be recognized by the makeobj program. In general, data which map directly to dat file values have a key (in the internal hash) that begins with an alphanumeric character; leading underscores are used for internal values.

Pak definitions for both the Standard and Extended (formerly "Experimental") versions for Simutrans are supported.

METHODS

new

  my $pak = Games::Simutrans::Pak->new;

Create a new Pak object. This module uses objects contructed with Mojo::Base. The following attributes, all optional, may be useful to pass when creating the object:

name

name

An identifying name for the pak. This must be the same as the name= value in the *.dat file which describes the Simutrans object.

from_string

  $pak->from_string( { file => $filename, text => $dat_text });

Parses the text in Simutrans's dat format as described at https://simutrans-germany.com/wiki/wiki/en_dat_Files. The file parameter was formerly used, and is still stored b

to_string

  my $text = $pak->to_string;

Returns a textual representation of the Pak object, designed to be able to be fed to the makeobj program. For example, each object will terminate with a line consisting only of several dashes, followed by a blank line. (In this way, several of these strings may be concatenated into a single *.dat file for correct processing by makeobj). The attribute lines are output in predesignated order, partially because of makeobj's requirements and partially to be sensible to human readers, starting with the following sequence:

obj=
type=
name=
copyright=

to_string in general will do its best to output ordinary values (whose keys do not begin with an underscore) whether scalar, hash, or array, in a format that the makeobj program will understand. to_string is guaranteed to skip processing for internal keys (beginning with an underscore) it does not recognize, and to give special processing to those it does recognize. This may be augmented later with a plugin system to permit user extensions.

intro

Returns or sets the object's introduction month, in the format year * 12 + month - 1, suitable for sorting or chronological comparison.

The methods intro_year and intro_month return or set the individual year and month components of the combined value.

retire

As intro, with component methods retire_year and retire_month.

waytype_text

Returns a standardized version of the object's waytype parameter, e.g., tram_track becomes just tram, and narrowgauge becomes just narrow.

payload_text

Returns a standardized version of the object's payload parameter. Missing payloads (as for locomotives) will return '--', classed payloads (as for passenger carriages) will be a comma-delimited sequence of numbers, and ordinary freight capacities will be in the form 100u (u for units).

IMAGE HANDLING

Simutrans generally handles the several images for an object as multi-level arrays. This module stores them as Perl hashes, with the key being the array index (usually a number, but some image types — e.g., Image and EmptyImage — use directional letters like S or SW). The value of a particular multidimensional position is in turn a hash which may contain these keys:

image

The name of the image file as given in the dat file, without path or extension. The existence of this key may be used to indicate the value describes and image.

imagefile

The image file with an absolute path (resolved as a relative path from the dat file itself) and extension (always .png as required by Simutrans).

x, y

The column and row number as given in the dat file.

xoff, yoff

The x and y offsets as given in the dat file, if defined; missing or undef are equivalent to zero.

INTERNAL KEYS

The following internal keys may be found in the hash representing an object.

_has_images

Nonzero if the object has attached images.

_is_permanent

Nonzero if the object is permanently defined in the game (it does not have an introduction or retire year).

_is_internal

Nonzero if the object is marked as internal to Simutrans itself; in the dat file it will have an intro_year less than 100.

_sort_key

Used for sorting the timeline, this contains text describing the introduction and retirement dates, along with the power (or other) text useful for human viewing of a sorted list.

AUTHOR

William Lindley <wlindley@cpan.org>

COPYRIGHT

Copyright 2021 William Lindley

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Games::Simutrans::Pak

Games::Simutrans::Image

Imager

Simutrans, https://simutrans.com/, is free software, an open-source transportation simulator.

The Simutrans Wiki, https://simutrans-germany.com/wiki/wiki/en_dat_Files, explains the format of *.dat files. They are normally fed, along with graphic *.png files, to the makeobj program to make the binary *.dat files that the Simutrans game engines use.