diy

DIY.cardVerison (default 1)
Sets the version of this component type that is created by this script. See onRead for a description of how a new version of an extension can be made backwards compatible. Note that this is property is an integer value. If you assign a value like "1.2" it will be silently rounded down.

DIY.extensionName (default null)
If set, this will be displayed to the user as part of the error message if the script file cannot be found. If a user opens a component for which the script file is not present, this allows Strange Eons to direct them to the extension they need to install in order to open the file.

DIY.faceStyle (default: FaceStyle.PLAIN_BACK)
This controls the number and type of faces (sides) that the component provides. The following values are possible:

FaceStyle.ONE_FACE	the component has only one face
FaceStyle.PLAIN_BACK	the component has a plain back (a fixed image)
FaceStyle.SHARED_FACE	the component has two faces, but they are identical
FaceStyle.TWO_FACES	the component has two different faces

If the style is set to ONE_FACE or SHARED_FACE, then any properties that pertain to the card's back face (such as backTemplateKey) will be ignored and paintBack() will never be called. If the style is set to PLAIN_BACK, then the backTemplateKey should point to an image resource for the back of the card. In this case again, paintBack() will not be called (the card back will be created automatically from the image resource).

DIY.frontTemplateKey (default: sm-misc-front-sheet)
This is the base name for a group of settings keys that describe the template image for the front face of the component. The template image determines the size of the component and is normally painted on the face to provide the component's background.

xxx-template	the resource file that contains the image
xxx-dpi	if present, the resolution of the template image in pixels per inch (2.54cm) (default is 150)
xxx-expsym-region	if present, the region where the expansion symbol is drawn (default is no expansion symbol)
xxx-expsym-invert	if yes, the inverted (white) expansion symbol is drawn (default is no
xxx-upsample	the upsample factor for previews (default is 1.0)

The upsample factor can be used when a component is likely to have very small text. It scales up the default resolution of the component when it is drawn in the preview window or exported. (For example, a factor of 2.0 would render the component at twice the normal resolution.) The only standard SE component that uses a value other than the default of 1.0 is the Monster token.

The template image for a face can be drawn in its respective paint function by calling sheet.paintTemplateImage( g );

DIY.backTemplateKey (default: sm-misc-back-sheet)
This property works the same as frontTemplateKey, but it controls the template image for the back face rather than the front. The property is ignored if the face style is not FaceStyle.PLAIN_BACK or FaceStyle.TWO_FACES.

DIY.portraitKey (default: null)
If this is not null, then the card has a portrait image and the editor will provide a tab for editing the portrait settings. The value is the base name of a setting key. To use a portrait, the following settings must also be defined (where xxx is the base name provided by portraitKey):

xxx-portrait-template	the resource file that contains the default portrait image
xxx-portrait-clip-region	this is the region where the portrait will be drawn on the card

In addition, the following settings are optional. If they are not present, then the portrait will default to a pan of (0,0) and the scale will be determined automatically using the size of the portrait image and the clip region.

xxx-portrait-scale	the scale setting for the default portrait image (where 1 = 100%)
xxx-portrait-panx	the number of units by which the default image is shifted horizontally (usually 0)
xxx-portrait-pany	the number of units by which the default image is shifted vertically (usually 0)

DIY.portraitBackgroundFilled (default: true)
If true, the portrait clip region will not be filled in with solid white before painting the portrait. This is usually set when the user is expected to use portraits that have transparency, for example, if there is a standard graphic that should appear behind the portrait image.

DIY.transparentFaces (default: false)
This flag indicates that the face(s) of this card may contain transparent and/or translucent pixels. This can be used to create faces with shaped edges. For example, if you wanted to make a new component for placing on boards similar to an Arkham or Other World Location. This flag should only be set when actually needed as transparent faces require more processor and memory resources that opaque cards.

DIY.variableSizedFaces (default: false)
This flag indicates that the component may vary in size depending on its content. The template image must be the maximum size that the card can grow to. The final size of the face will be determined after it is painted by cropping off any edges that are completely transparent (i.e., have an alpha value of 0). Setting this flag to true automatically sets DIY.transparentFaces to true.

DIY.portraitScaleUsesMinimum (default: false)
This flag changes how the defualt scale is selected when the user chooses a new portrait image. Normally, a portrait is scaled so that the card's portrait clip region is just barely completely covered, so that no background shows through. When this flag is set to true, the portrait is scaled so that the entire image is just contained within the clip region. This is useful when there is one standard background shared by all components and the portraits themselves are a transparent "cut-out" that will be drawn over this standard background.

DIY.portraitClipping (default: true)
If set to true (the default), then the portrait will be clipped to the portrait clipping region: any part of the portrait that falls outside of the clip region will not be drawn. When set to false, the portrait clip region will only be used to determine the initial scale of a portrait.

DIY.deckSnappingHint (default: DeckSnappingHint.CARD)
This setting controls how this component will initially snap to other components when it is in a deck. The possible values are:

DeckSnappingHint.CARD	This is a card; it will have crop marks and snap to other cards and the page grid.
DeckSnappingHint.TILE	This is a tile (a basic building block for an expansion board). It will not have crop marks and it will snap to other tiles and the page grid.
DeckSnappingHint.OVERLAY	This component is overlaid over other components (usually tiles). Overlays do not snap to other components or the page grid and do not have crop marks.
DeckSnappingHint.INLAY	This is an inlay. Inlays snap to other inlays, tiles and the page grid, but when they snap to objects other than inlays they snap to the inside rather than the outside of the snapping edge.
DeckSnappingHint.OTHER	Objects with this hint snap only to other objects with this hint. They are not given crop marks.

DIY.bleedMargin (default: 0)
This indicates the size of an optional margin around the edges of a component that is to be used as a bleed margin. A bleed margin is an area where the graphics of a card continue outside of the normal boundary of the card. This allows for imprecision when the card is cut by machine. If the machine is misaligned by a small amount, the card content will be slightly off center but it won't have a blank area along the edge(s) that would make the misalignment obvious. When a margin value is set, the crop marks produced by the deck editor are automatically adjusted accordingly.

If a bleed margin is set, the same value is used on all four sides. The size of the margin is measured in points (pt) and cannot be negative. Typical bleed margin sizes in the publishing industry are 3 mm (8.5 pt) or 1/8" (9 pt).

Setting the margin value does not change the underlying graphics. You must design your template image with a bleed margin in mind, adding pixels equal to twice the margin size to both the width and height, and centering the "real" card template in the larger space. For example, if your template image is 150 DPI and you wish to include a 9 pt margin, you must add:
150 pixels/in / 72 pt/in * 9 pt * 2 sides = 38 pixels (after rounding up)

DIY.highResolutionSubstitutionMode (default: enabled)
This controls whether high resolution image substitution is enabled. When enabled, methods defined in DIYSheet that paint images will automatically check for a copy of the image key that ends with -hires. If that key exists, then that image will be substituted when the card is being printed or exported at a resolution higher than that of the card's template image. For example, suppose we provide the following keys for a card's front template image:

 my-card-front-template = mycard/front-150.jp2
 my-card-front-dpi = 150
 my-card-front-template-hires = mycard/front-300.jp2

Then when the card is printed or exported at more than 150 DPI, the alternate template image will be substituted by DIYSheet.paintTemplateImage.

Changing this property allows you to force substitution on or off. It is normally only changed for debugging purposes. Unlike other properties listed here, this can be changed at any time. The possible values are:

HighResolutionMode.DISABLE	do not allow substitution
HighResolutionMode.ENABLE	allow substitution using the normal rules
HighResolutionMode.FORCE	always substitute if possible

DIY.setCustomFoldMarks( faceIndex, foldMarkVectors ) (default: none)
Defines custom fold marks for a card face. These will be drawn with the face when it is added to a deck. The faceIndex defines the card face (0=front, 1=back) to add marks for, although usually such a card would only have a front side. The array foldMarkVectors consists of one or more pairs of points (four numbers in sequence) in the order (px,py),(dx,dy). The point (px,py) is indicates the location of the start of the fold mark (assuming that the distance from the card to the fold mark is 0). The point is measured realtive to the width and height of the card. For example, (0.5, 0.0) is located at the middle of the top edge of the card. The point (dx,dy) is a unit vector that indicates the direction of the mark. For example, the unit vector (0,-1) points straight up.

DIY.advancedFlags (default: all flags off)
This setting is a bit mask that controls advanced options for painting the component. In most cases, this should be left as-is. These flags may be used to enable experimental features, or to create cards which optionally use certain fetaures only in versions of Strange Eons that support them. If you are not sure of what you are doing, it is best to leave this alone.

 function create( diy ) {
     diy.cardVersion = 2;
 }
 // ...
 function onRead( diy, objectInputStream ) {
    if( diy.cardVersion < 2 ) {
        // set settings that are new in v2 to a default value
        // ...
        diy.cardVersion = 2; // this card is now the latest version
    }
 }

 var diy = DIY.createTestInstance( new arkham.diy.Handler() {
     create: function() { println( "create" ); },
     createInterface: function() { println( "createInterface" ); },
     createFrontPainter: function() { println( "createFrontPainter" ); },
     createBackPainter: function() { println( "createBackPainter" ); },
     paintFront: function() { println( "paintFront" ); },
     paintBack: function() { println( "paintBack" ); },
     onClear: function() { println( "onClear" ); },
     onRead: function() { println( "onRead" ); },
     onWrite: function() { println( "onWrite" ); },
 });
 var ed = diy.createDefaultEditor();
 Eons.addEditor( ed );

 if( sheet.renderingQuality > DIYSheet.QUALITY_PREVIEW ) {
     // print or export
 } else {
     // preview
 }