diff --git a/doc/type/alignment.txt b/doc/type/alignment.txt new file mode 100644 index 00000000..52f68003 --- /dev/null +++ b/doc/type/alignment.txt @@ -0,0 +1,29 @@ +Enumeration: alignment + +Specifies how text and images are aligned in boxes. +An alignment consists of a vertical and a horizontal component. +Optionally there are some modifiers. + +--Script syntax-- +In scripts, alignment is passed around as a string. + +--Possible values-- +The value is a combination of one or more flags, separated by spaces. +! Value Description +| @left@ Horizontally, align at the left +| @center@ Horizontally, align in the middle +| @right@ Horizontally, align at the right +| @top@ Vertically, align at the top +| @middle@ Vertically, align in the middle +| @bottom@ Vertically, align at the bottom +| @justify@ Move characters apart or together to exactly fill the width of the box. +| @justify-words@ Move words apart or together to exactly fill the width of the box. +| @justify-overflow@ If the text becomes to long, move characters closer together. +| @stretch Stretch text, so it always fills the width of the box.
+ For images; stretch them, but preserve the aspect ratio. +| @stretch-overflow@ Stretch (compress) the text when it becomes too long. + +--Examples-- +> alignment: top left +> alignment: middle center +> alignment: { "middle" + " " + "left" } diff --git a/doc/type/boolean.txt b/doc/type/boolean.txt new file mode 100644 index 00000000..602e91a0 --- /dev/null +++ b/doc/type/boolean.txt @@ -0,0 +1,24 @@ +Primitive type: boolean + +A boolean is either @true@ or @false@. + +In a script, numbers are implicitly converted to booleans, a non-zero number is @true@, 0 is @false@. + +When converted to a number, @true@ becomes @1@ and @false@ becomes @0@. + +The strings @"yes"@ and @"no"@ can also be converted to booleans. + +--File syntax-- +> boolean: true +> boolean: false + +--Script syntax-- +> true or false + +The operators @or@, @and@ and @xor@ combine two booleans: +! @a@ @b@ a or b a and b a xor b +| @false@ @false@ @false@ @false@ @false@ +| @false@ @true@ @true@ @false@ @true@ +| @true@ @false@ @true@ @false@ @true@ +| @true@ @true@ @true@ @true@ @false@ + diff --git a/doc/type/combine.txt b/doc/type/combine.txt index 506d274f..4994475c 100644 --- a/doc/type/combine.txt +++ b/doc/type/combine.txt @@ -1,7 +1,41 @@ -==Data type: image combine type== +Enumeration: image combine type This specifies how an image is to be combined with the background. This is similair to the feature found in more advanced drawing programs. +The formula's are from [[http://www.pegtop.net/delphi/articles/blendmodes/]]. + +--Script syntax-- +In scripts, combine modes are stored as a string. + --Possible values-- -| overlay \ No newline at end of file +! Value Description +| @normal@ Normal behaviour, don't combine. +| @add@ +| @subtract@ +| @stamp@ +| @difference@ +| @negation@ +| @multiply@ +| @darken@ +| @lighten@ +| @color dodge@ +| @color burn@ +| @screen@ +| @overlay@ +| @hard light@ +| @soft light@ +| @reflect@ +| @glow@ +| @freeze@ +| @heat@ +| and Bitwise and +| or Bitwise or +| xor Bitwise xot +| @shadow@ Dark colors normally, white colors darken the background. +| @symmetric overlay@ @(overlay(a,b) + overlay(b,a)) / 2@ + +--Examples-- +> combine: overlay +> combine_image(image1: ..., image2: ..., combine: "shadow") + diff --git a/doc/type/dependency.txt b/doc/type/dependency.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/direction.txt b/doc/type/direction.txt new file mode 100644 index 00000000..5a3e1c9f --- /dev/null +++ b/doc/type/direction.txt @@ -0,0 +1,20 @@ +Enumeration: direction + +Specifies the direction of text flow in a text box. + +--Script syntax-- +In scripts, direction is passed around as a string. + +--Possible values-- +! Value Description +| @left to right@ Text starts at the left. +| @right to left@ Text starts at the right ''(currently not implemented)'' +| @top to bottom@ Text starts at the top, each character is on a new line. +| @bottom to top@ Text starts at the bottom ''(currently not implemented)'' +| @horizontal@ Same as @left to right@. +| @vertical@ Same as @top to bottom@. + +--Examples-- +> direction: horizontal +> direction: top to bottom + diff --git a/doc/type/double.txt b/doc/type/double.txt new file mode 100644 index 00000000..f107c838 --- /dev/null +++ b/doc/type/double.txt @@ -0,0 +1,15 @@ +Primitive type: real number + +Real or floating point numbers are numbers with a decimal point. + +Conversio from integer to real numbers happens automatically in scripting. + +--File syntax-- +> something: 123 +> something: 0.5 + +--Script syntax-- +> 123.1 + 456 * -1 + +--See also-- +* [[type:int]] diff --git a/doc/type/field.txt b/doc/type/field.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/filename.txt b/doc/type/filename.txt new file mode 100644 index 00000000..e3816c35 --- /dev/null +++ b/doc/type/filename.txt @@ -0,0 +1,10 @@ +Primitve type: filename + +Filenames are regular [[type:string]]s, pointing to a file. +There are two types of filenames, relative and absolute: +! Syntax Description +| path/to/file A relative file, this is retrieved from the current package. + i.e. for a filename in a stylesheet, the file is retrieved from that stylesheet. +| /package/path/to/file An absolute filename includes the name of the package. This is a package somewhere in the MSE data directory. + +Don't forget the double quotes (@""@) in scripts. diff --git a/doc/type/game.txt b/doc/type/game.txt index 39bbd8c2..4d4545dd 100644 --- a/doc/type/game.txt +++ b/doc/type/game.txt @@ -20,21 +20,21 @@ Such a package contains a data file called game that has the following | @mse version@ [[type:version]] ''required'' Version of MSE this game is made for. | @short name@ [[type:string]] file name A short name of this game, for the 'new set' list. | @full name@ [[type:string]] file name A longer name of this game. -| @icon@ [[type:filename]] ''none'' Filename of an icon for this card, for the 'new set' list. +| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this game, for the 'new set' list. | @position hint@ [[type:int]] ∞ Where to place this item in the 'new set' list? Lower numbers come first. | @version@ [[type:version]] @0.0.0@ Version number of this package. | @depends on@ [[type:list]] of [[type:dependency]]s Packages this package depends on. | '''Specific to games''' <<< <<< <<< -| @init script@ [[type:script]] @;@ Script to run when this game is loaded, can set variables +| @init script@ [[type:script]] @;@ Script to run when this game is loaded,
can set variables to be used by other scripts in this game or stylesheets using it. | @set fields@ [[type:list]] of [[type:field]]s Fields for the styling panel. | @default set style@ [[type:indexmap]] of [[type:style]]s Default style for the set fields, can be overriden by the stylesheet. | @card fields@ [[type:list]] of [[type:field]]s Fields for each card. -| @card list color script@ [[type:script]] from fields Script that determines the color of an item in the card list. If not set uses the @card list colors@ property of the first card field that has it. -| @statistics dimensions@ [[type:list]] of [[type:statistics dimension]]s from fields Dimensions for statistics, a dimension is rougly the same as an axis. By default all card fields with 'show statistics' set to true are used. -| @statistics categories@ [[type:list]] of [[type:statistics category]]s from dimensions Choices shown on the statistics panel. By default all statistics dimensions are used. +| @card list color script@ [[type:script]] from fields Script that determines the color of an item in the card list.
If not set uses the @card list colors@ property of the first card field that has it. +| @statistics dimensions@ [[type:list]] of [[type:statistics dimension]]s from fields Dimensions for statistics, a dimension is rougly the same as an axis.
By default all card fields with 'show statistics' set to true are used. +| @statistics categories@ [[type:list]] of [[type:statistics category]]s from dimensions Choices shown on the statistics panel.
By default all statistics dimensions are used. | @has keywords@ [[type:boolean]] @false@ Does this game use keywords? Should the keywords tab be available? | @keyword match script@ [[type:script]] @;@ Script to apply to the @match@ property of keywords. | @keyword modes@ [[type:list]] of [[type:keyword mode]]s Choices for the 'mode' property of keywords. diff --git a/doc/type/index.txt b/doc/type/index.txt index c208cac3..88e8584d 100644 --- a/doc/type/index.txt +++ b/doc/type/index.txt @@ -18,13 +18,18 @@ These are the 'major' data types that are written directly to [[file:package]]s. --Compound types-- These contain several properties, similair to the file types. But they are part of some other file type. -| [[type:field]] A field description for cards. -| [[type:style]] The styling and positioning of a field. -| [[type:value]] The value in a field, for a particular card. -| [[type:card]] A card containing values. -| [[type:keyword]] A keyword. -| [[type:font]] Description of a font. -| [[type:symbol part]] Part of a [[type:symbol]]. +| [[type:field]] A field description for cards. +| [[type:style]] The styling and positioning of a field. +| [[type:value]] The value in a field, for a particular card. +| [[type:card]] A card containing values. +| [[type:keyword]] A keyword. +| [[type:keyword mode]] A possible mode for keywords. +| [[type:keyword param type]] A type of parameters for keywords. +| [[type:statistics dimension]] A dimension for the statistics panel. +| [[type:statistics category]] A category for the statistics panel. +| [[type:font]] Description of a font. +| [[type:symbol part]] Part of a [[type:symbol]]. +| [[type:control point]] A point on in a symbol part. --Collection types-- | [[type:list]] Lists of items @@ -42,8 +47,18 @@ These contain several properties, similair to the file types. But they are part | [[type:image]] An image defined by a script. | [[type:function]] Functions in scripts. These have no direct representation in a file. +--Enumerations-- +| [[type:alignment]] Alignment of text and images +| [[type:direction]] Direction of text +| [[type:combine]] How to combine images with the background + --Primitive types-- -| [[type:string]] Text, @"abc"@ -| [[type:int]] Integer numbers, @1, 2, 100@ -| [[type:double]] Real numbers, @1, 0.5, 21.3@ -| [[type:color]] Colors +| [[type:string]] Text, @"abc"@ +| [[type:tagged string]] Text with tags +| [[type:filename]] Filenames +| [[type:regex]] Regular expression strings +| [[type:boolean]] @true@ or @false@ +| [[type:int]] Integer numbers, @1, 2, 100@ +| [[type:double]] Real numbers, @1, 0.5, 21.3@ +| [[type:version]] Version numbers +| [[type:color]] Colors diff --git a/doc/type/indexmap.txt b/doc/type/indexmap.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/int.txt b/doc/type/int.txt new file mode 100644 index 00000000..b70d7c6b --- /dev/null +++ b/doc/type/int.txt @@ -0,0 +1,13 @@ +Primitive type: integer number + +Integer numbers are numbers without a decimal point. +In many cases negative numbers don't make sense, but the program never complains about them. + +--File syntax-- +> something: 123 + +--Script syntax-- +> 123 + 456 * -1 + +--See also-- +* [[type:double]] diff --git a/doc/type/keyword.txt b/doc/type/keyword.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/keyword_mode.txt b/doc/type/keyword_mode.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/keyword_param_type.txt b/doc/type/keyword_param_type.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/list.txt b/doc/type/list.txt index 1972fb8f..3f41ee95 100644 --- a/doc/type/list.txt +++ b/doc/type/list.txt @@ -21,6 +21,7 @@ The first element of a list is numbered 0, the next 1, etc. > list.0 # The first element of the list 'list' > list[0] # The same thing +--Functions-- There are several functions for working with lists: | [[fun:position]] Find the position of an element in a list | [[fun:number_of_items]] Find the number of items in a list diff --git a/doc/type/map.txt b/doc/type/map.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/set.txt b/doc/type/set.txt index 67387f46..4e661e74 100644 --- a/doc/type/set.txt +++ b/doc/type/set.txt @@ -1,85 +1,61 @@ -==Object type: Set== +File type: Set ---Package-- -A set is described in a package with the .mse-set file extension, +--Overview-- + +Sets are part of the [[file:style triangle]]: +| Description Looks Data +| [[type:Game]] [[type:Stylesheet]] '''Set''' +| [[type:Field]] [[type:Style]] [[type:Value]] + +--Package format-- +A set is described in a [[file:package]] with the .mse-set file extension, such a package contains a data file called set. --Properties-- -| game Name of a [[type:game]] The game this set is made for. -| stylesheet Name of a [[type:stylesheet]] The default style for drawing cards in this set. -| set info [[type:indexmap]] of [[type:value]]s The data for the [[prop:game:set fields]] defined in the game. -| styling [[type:indexmap]] of [[type:value]]s -| cards [[type:list] of [[type:card]]s The cards in the set. +! Property Type Default Description +| '''Common to all packages''' <<< <<< <<< +| @mse version@ [[type:version]] ''required'' Version of MSE this set is made with. +| @short name@ [[type:string]] file name Name of this set. +| @depends on@ [[type:list]] of [[type:dependency]]s + Packages this package depends on. + +| '''Specific to sets''' <<< <<< <<< +| game Name of a [[type:game]] ''required'' The game this set is made for. +| stylesheet Name of a [[type:stylesheet]] ''required'' The default style for drawing cards in this set. +| set info [[type:indexmap]] of [[type:value]]s The data for the [[prop:game:set fields]] defined in the game. +| styling [[type:map]] of [[type:indexmap]]s of [[type:value]]s + Data for the 'extra fields' of the stylesheet.
+ This is first indexed by stylesheet name, then by field name.
+ Data is given not only for the set's stylesheet but also for those of cards. +| cards [[type:list] of [[type:card]]s The cards in the set. +| keywords [[type:list] of [[type:keyword]]s The custom keywords in the set. --Example-- -|- -| set info: -| Contains custom information about the set, corresponding to the set fields in the game. -|- -| extra set info: -| Contains information about the set for a specific style, corresponding to the extra fields in the style.
- Stored with an index for the game, see the example below. -|- -| card:
card:
... -| Contains information about each card, corresponding to the card fields in the game. -|- -| keyword:
keyword:
... -| Extra keywords specific to this set, in addition to those defined in the game. - For more information see the game file -|} - -The set info and cards contain a list of keys that correspond to the names fields in the game, -For example if the game looks like: - name: my game - set field: - name: copyright - type: text - card field: - name: card name - type: text - card field: - name: power - type: text - -The the set file looks like: - game: my game - name: my set - set info: - copyright: something - extra set info: - name-of-style: - name-of-field: something - card: - card name: first card - power: 100 - card: - card name: second card - power: 50 - - -The value that is stored depends on the type of field of course, in the above example the fields have type: text, so the value is just the text. -For other types of fields the value is encoded as follows: -{| -! Attribute !! Description -|- -| text -| The text that is stored in the field. This text can contain tags. -|- -| choice -| One of the choices specified in the game. -|- -| boolean -| One of yes or no. -|- -| color -| The color is encoded as rgb(red,green,blue) where red, green and blue are numbers between 0 and 255 that indicate the color components. -|- -| image -| The filename containing the image, this file must also be in the set package. It can be empty to indicate that no image is selected. -|- -| symbol -| The filename containing the symbol specification, this file must also be in the set package. - It can be empty to indicate that no symbol is selected. -|} -If a field has the default value (calculated by the default script), then the field name and value are ommited from the set file. +If the game looks like: +>mse version: 0.3.4 +>name: my game +>set field: +> name: copyright +> type: text +>card field: +> name: card name +> type: text +>card field: +> name: power +> type: text +The the a set file would looks like: +>mse version: 0.3.4 +>game: my game +>name: my set +>set info: +> copyright: something +>extra set info: +> name of style: +> name of field: something +>card: +> card name: first card +> power: 100 +>card: +> card name: second card +> power: 50 diff --git a/doc/type/statistics_category.txt b/doc/type/statistics_category.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/statistics_dimension.txt b/doc/type/statistics_dimension.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/string.txt b/doc/type/string.txt index 6f11b43a..de8aba64 100644 --- a/doc/type/string.txt +++ b/doc/type/string.txt @@ -1,5 +1,28 @@ -==Data type: character string== +Primitive type: character string + +A string is just a piece of text. --File syntax-- +In files, strings are written just as their value: +> string: this is some string +The whitespace at the beginning is removed by the program. +Multiline strings are written on a new line, indented by a TAB: +> string: +> This is a very long string +> It contains a line break. ---Script syntax-- \ No newline at end of file +--Script syntax-- +In scripts, strings are written between double quotes, @"this is a string"@. +The backslash character is used to escape values: +! Code Represents +| @\"@ A " character +| @\{@ A { character +| @\n@ A newline character (line break) +| @\\@ A backslash +| @\<@ An escaped < for [[type:tagged string]]s. + +Sections between curly braces are interpreted as script code, that is concatentated with the string, for example +> "ab{1 + 1}c" == "ab2c" +This can be nested arbitrarily. + +The @+@ operator concatenates strings. Numbers and most other values are automatically converted to strings when needed. diff --git a/doc/type/style.txt b/doc/type/style.txt new file mode 100644 index 00000000..e69de29b diff --git a/doc/type/stylesheet.txt b/doc/type/stylesheet.txt index 33c8863f..be25ac6b 100644 --- a/doc/type/stylesheet.txt +++ b/doc/type/stylesheet.txt @@ -1,12 +1,42 @@ Object type: Stylesheet ---Properties-- -| @game@ Name of a [[type:game]] Game this stylesheet is made for -| @init script@ [[type:script]] -| @card width@ [[type:double]] Width of cards in pixels -| @card height@ [[type:double]] Height of cards in pixels -| @card dpi@ [[type:double]] Resoltion of cards in dots-per-inch -| @card background@ [[type:color]] Background color of cards -| @card style@ [[type:indexmap] of [[type:style]]s Styles for the [[property:game:card fields]] defined in the game -| +--Overview-- + +Stylesheets are part of the [[file:style triangle]]: +| Description Looks Data +| [[type:Game]] '''Stylesheet''' [[type:Set]] +| [[type:Field]] [[type:Style]] [[type:Value]] + +Stylesheets provide the ''look and feel'' of cards. + +--Package format-- +A stylesheet is described in a [[file:package]] with the .mse-style file extension, +such a package contains a data file called style. + +--Properties-- +! Property Type Default Description +| '''Common to all packages''' <<< <<< <<< +| @mse version@ [[type:version]] ''required'' Version of MSE this stylesheet is made for. +| @short name@ [[type:string]] file name A short name of this stylesheet, for the 'new set' and style panel lists. +| @full name@ [[type:string]] file name A longer name of this stylesheet. +| @icon@ [[type:filename]] ''none'' Filename of an icon / preview for this stylesheet, for the 'new set' and style panel lists. +| @position hint@ [[type:int]] ∞ Where to place this item in the list? Lower numbers come first. +| @version@ [[type:version]] @0.0.0@ Version number of this package. +| @depends on@ [[type:list]] of [[type:dependency]]s + Packages this package depends on. + +| '''Specific to stylesheets''' <<< <<< <<< +| @game@ Name of a [[type:game]] ''required'' Game this stylesheet is made for +| @card width@ [[type:double]] 100 Width of cards in pixels +| @card height@ [[type:double]] 100 Height of cards in pixels +| @card dpi@ [[type:double]] 96 Resoltion of cards in dots-per-inch +| @card background@ [[type:color]] white Background color of cards +| @init script@ [[type:script]] @;@ Script to run when this stylesheet is loaded, after the game's init script. +| @styling fields@ [[type:list] of [[type:field]]s Fields for styling options, shown on the 'style' panel. +| @styling style@ [[type:indexmap] of [[type:style]]s Styles for the styling fields. +| @set info style@ [[type:indexmap] of [[type:style]]s game.default_set_style Styling for the 'set info' panel +| @card style@ [[type:indexmap] of [[type:style]]s Styles for the card fields defined in the game +| @extra card fields@ [[type:list] of [[type:field]]s Additional fields to add to each card.
+ These fields are intended for things like lines and boxes, whose value is determined automatically. +| @extra card style@ [[type:indexmap] of [[type:style]]s Styling for the extra card fields diff --git a/doc/type/version.txt b/doc/type/version.txt new file mode 100644 index 00000000..2cbc8199 --- /dev/null +++ b/doc/type/version.txt @@ -0,0 +1,11 @@ +Primitive type: version number + +--File syntax-- +A version number consists of three components, in the form "a.b.c". +Higher numbers mean newer versions. + +The version number can also be a date, of the form "YYYY-MM-DD" + +--Examples-- +> version: 1.2.3 +> version: 2007-07-12