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:
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
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.