About

Installation

Copy the "dire" directory to your game path. Follow the instructions in the component description.

Components

Core

require "dire/core"

Rect

{
    x: number,
    y: number,
    w: number,
    h: humber
}

dire_draw_center(src: Pixels, dst: Pixels, position: Rect)

Draw image centered in provided position

dire_draw_tile(src: Pixels, dst: Pixels, position: Rect, options: table)

Draw image tiled in provided position.

options.xoffset and options.yoffset mark offset from top left corner. There are two special values: -1 -- center, -2 -- right/bottom.

dire_draw_letterbox(src: Pixels, dst: Pixels, position: Rect, options: table)

Draw image letterboxed in provided position.

options.smooth defines whether scaled image should be smoothed or not

dire_draw_fill(src: Pixels, dst: Pixels, position: Rect, options: table)

Draw image filling provided position.

options.smooth defines whether scaled image should be smoothed or not

dire_draw_stretch(src: Pixels, dst: Pixels, position: Rect, options: table)

Draw image stretch to provided position.

options.smooth defines whether scaled image should be smoothed or not

dire_draw_9(src: Array<Pixels>, dst: Pixels, position: Rect, options: table) or (fields: Array<Tuple<Function, Pixels, Pixels, Rect, table>>)

9-slice scaling splits initial image into 9 areas, indices are corresponding to the oines on the scheme below.

+---+---+---+
|   |   |   |
| 1 | 2 | 3 |
|   |   |   |
+---+---+---+
|   |   |   |
| 4 | 5 | 6 |
|   |   |   |
+---+---+---+
|   |   |   |
| 7 | 8 | 9 |
|   |   |   |
+---+---+---+

Parts 1, 3, 7, 9 are not scaled and positioned as is, parts 2 and 8 are only scaled horizontally, parts 4 and 6 -- vertically, and only part 5 is scaled in both directions. This is useful for UI elements like buttons, frames, etc.

Draw image 9-slice scaled over position. For options see dire_map_9.

fields -- are fields returned by dire_map_9.

dire_map_9(src: Array<Pixels>, dst: Pixels, position: Rect, options: table) -> Array<Tuple<Function, Pixels, Pixels, Rect, table>>

options.parts -- object returned by dire_slice_9 as second value. It contains widths and heights of each of the src items. options.drawmethod -- what draw method to use for scaling(1 -- center, 2 -- tile, 3 -- letterbox, 4 -- fill, 5 -- stretch) each part. Can be a single number or an array of 9 numbers. options.drawoptions -- options for target method(as in correspondiing function), can be a single table or an array of 9 tables.

Map parameters to an array for dire_draw_9, or it is possible to manually call each of the functions in the array, providing all the other tuple items as arguments

dire_slice_9(src: Pixels, slice: Rect)

Slice src into 9 pixels objects to be used by dire_draw_9 or dire_map_9.

slice defines central rectangle.

Layout

require "dire/layout"

Constraint

{
    bottomof: Constraint or Rect, -- Strictly align below specified Rect/Constraint. Constraint will be resolved in current canvas.
    rightof: Constraint or Rect, -- Strictly align right of specified Rect/Constraint. Constraint will be resolved in current canvas.
    leftof: Constraint or Rect, -- Strictly align left of specified Rect/Constraint. Constraint will be resolved in current canvas.
    topof: Constraint or Rect, -- Strictly align above specified Rect/Constraint. Constraint will be resolved in current canvas.
    wf: number, -- Take at most wf fraction of the allowed width. Default: 1
    hf: number, -- Take at most hf fraction of the allowed height. Default: 1
    wmax: number, -- Maximum width (actual Rect will not exceed wf of width). Default: infinity
    hmax: number, -- Maximum height (actual Rect will not exceed wf of width). Default: infinity
    wmin: number, -- Minimum width. Default: 1
    hmin: number, -- Minimum height. Default: 1
    lx: number, -- Left margin to keep. May be reduced if violating wmin
    ty: number, -- Top margin to keep. May be reduced if violating hmin
    rx: number, -- Right margin to keep. May be reduced if violating wmin
    by: number, -- Bottom margin to keep. May be reduced if violating hmin
    rmax: number, -- Maximum aspect ratio
    rmin: number -- Minimum aspect ratio
    -- width or height may be reduced below wmin/hmin if out of rmax/rmin
    ax: number, -- Horizonal alignment. Negative numbers align to the left(lx will always be satisfied, rx is only used to shrink area), Positive numbers align to the right(rx will always be satisfied, lx is only used to shrink area), zero aligns to the center(both lx and rx are only used to shink area). 1 and -1 give preference to opposite margin.
    ay: number -- Vertical alignment, same as horizonal. Negative -- align to the top, positibe -- to the bottom, zero -- to the center. 1 and -1 give preference to opposite margin.
    pf: function -- Post-processing function, accepts Rect returned by basic constraint processing, returns another Rect. This Rect should fit inside original Rect to avoid layout breakage
    noscale: boolean -- disable scaling by diretheme
    dx: number -- x offset that will be applied to coordinates
    dy: number -- y offset that will be applied to coordinates
}

constraint_to_rect(constraint: Constraint, canvas: Rect): Rect

Resolve Constraint to Rect within canvas. Returned Rect is guaranteed to be within canvas.

Theme

require "dire/theme"

Font

{
    color: string -- basic text color in #FFFFFF format
    link: string -- link color in #FFFFFF format
    alink: string -- hovered link color in #FFFFFF format
    font: string -- font file name
    size: number -- font size. Only integer value is supported!
    height: number -- proportional line height. Default: 1.0
    noscale: boolean -- disable scaling by diretheme
}

Position

Position is always relative to parent contentrect. Negative values are subtracted from right border, positive numbers are added tp the left border. Nil values mean default.

{
    x: number,
    y: number,
    ax: number, -- positive or 0 means right, negative means left
    ay: number -- positive or 0 means top, negative means bottom
}

set_theme()

Immediately apply configured theme. Used internally. Most likely you don't need to call this function manually.

set_scale(scale: number)

Sets scale to the specified value. If scale == nil or scale == false then reset scale to it's default value.

set_cursor(options: table, reset: boolean)

Sets cursor parameters. If reset is true -- replace all values, Otherwise only update values present in the current call.

Pass empty table to options to reset to defaults.

Valid options:

• normal: string or Pixels -- image with normal cursor

• use: string or Pixels -- image with use cursor

• x: number -- cursor active point position

• y: number -- cursor active point position

• scale: boolean -- should cursor be scaled with scale

set_menu(options: table, reset: boolean)

Sets menu parameters. If reset is true -- replace all values, Otherwise only update values present in the current call.

Valid options:

• leftof, topof, bottomof, rightof: "inv", "menu", "text", "image" -- location relative to other areas

• button: table -- button parameters

  • image: string or Pixels -- image with button

  • options: ScalingOptions

• buttonrect: Constraint -- button area definition

• bg: table -- menu background definition

  • color -- color in #DDDDDD format

  • alpha -- alpha 0..255

  • border: table

    • color -- color in #DDDDDD format

    • width -- width of the border

• height: number -- see instead menu.fnt.height

• text: Font

• scaleui: number -- 0 -- not scale, 1 -- scale area, but not image, 2 -- scale image, but not area, 3 -- scale image and area

set_inventory_area(options: table, reset: boolean)

Sets inventory parameters. If reset is true -- replace all values, Otherwise only update values present in the current call.

Valid options:

• leftof, topof, bottomof, rightof: "inv", "menu", "text", "image" -- location relative to other areas

• rect: Constraint -- definition of area position

• contentrect: Constraint -- definition on actual inventory area. Relative to rect.

• uppos: Position -- position of up scroller

• downpos: Position -- position of down scroller

• up: string | Pixels -- scroll up button image

• down: string | Pixels-- scroll down button image

• mode: string -- see instead inv.mode

• text: Font

• height: number -- see instead inv.fnt.height

• bg: table -- background definition. Background will be drawn over rect

  • color -- color in #DDDDDD format

  • alpha -- alpha 0..255

  • image -- background image (can be a function)

  • options -- background image scaling options. Specific options are defined by mode are correspond to options of dire_draw_* method.used.

    • mode -- defines function(1-5 as in drawmethod, 6 -- 9-scale)

    • drawmethod -- secondary draw method for parts of 9-scaled image.

    • slice -- rect, defining center area of 9-scaled image

    • scale -- boolean value, defining should image be scaled or not(before stretching)

set_text_area(options: table, reset: boolean)

Sets text parameters. If reset is true -- replace all values, Otherwise only update values present in the current call.

Valid options:

• leftof, topof, bottomof, rightof: "inv", "menu", "text", "image" -- location relative to other areas

• rect: Constraint -- definition of area position

• contentrect: Constraint -- definition on actual text area. Relative to rect.

• uppos: Position -- position of up scroller

• downpos: Position -- position of down scroller

• up: string | Pixels -- scroll up button image

• down: string | Pixels-- scroll down button image

• align: string -- see instead win.align

• height: number -- see instead win.fnt.height

• scrollmode: string -- see instead win.scroll.mode

• waysmode: string -- see instead win.ways.mode

• text: Font

• bg: table -- background definition. Background will be drawn over rect

  • color -- color in #DDDDDD format

  • alpha -- alpha 0..255

  • image -- background image (can be a function)

  • options -- background image scaling options. Specific options are defined by mode are correspond to options of dire_draw_* method.used.

    • mode -- defines function(1-5 as in drawmethod, 6 -- 9-scale)

    • drawmethod -- secondary draw method for parts of 9-scaled image.

    • slice -- rect, defining center area of 9-scaled image

    • scale -- boolean value, defining should image be scaled or not(before stretching),

set_image_area(options: table, reset: boolean)

Sets image area parameters. If reset is true -- replace all values, Otherwise only update values present in the current call.

Image area is only drawn if mode is float. In other modes it is only calculated, but not drawn.

• leftof, topof, bottomof, rightof: "inv", "menu", "text", "image" -- location relative to other areas

• rect: Constraint -- definition of area position

• contentrect: Constraint -- definition on actual image area. Relative to rect.

• mode: string -- see scr.gfx.mode

• bg: table -- background definition. Background will be drawn over rect

  • color -- color in #DDDDDD format

  • alpha -- alpha 0..255

  • image -- background image (can be a function)

  • options -- background image scaling options. Specific options are defined by mode are correspond to options of dire_draw_* method.used.

    • mode -- defines function(1-5 as in drawmethod, 6 -- 9-scale)

    • drawmethod -- secondary draw method for parts of 9-scaled image.

    • slice -- rect, defining center area of 9-scaled image

    • scale -- boolean value, defining should image be scaled or not(before stretching),

set_background(color: string, alpha: number, image: string | Pixels | Function(tgt, options, rect), options: table)

define background. Color -- html-format color specification. alpha -- 0..255 alpha

Options:

- options.mode -- defines stretching mode (as dire),

- options.scale -- boolean value, defining should image be scaled or not(before stretching),

- other options define scaling paramehters,

set_canvas(canvas: Constraint)

define constraint for canvas. Everything except the background is positioned relative to canvas.

get_canvas(): Rect

retrieves current canvas

get_inches(): Number

retrieves screen size in inches

get_screen(): Tuple<Number, Number>

retrieves real resolution

get_scaled_screen(): Tuple<Number, Number>

retrieve logical resolution (divided by scale, rounded up)