charactersheet/doc/specifications_rcs_file_format.md

0001 # Specification about rcs file.
0002
0003 The rcs file is a json file. It is gathering all information about the charactersheet.
0004 Data to generate the qml code, the qml code, and data about characters.
0005
0006 ## Background
0007
0008 The background key is an array of object. This object has two keys:
0009
0010 **bin** : data of the image saved in base64
0011 **key** : id of the image (used in QML to point the image)
0012
0013 The key must have this scheme: "{a41e1438-0aee-46d1-8714-2a284634df77}_background_0.jpg"
0014 If you have many background images the only difference between key must be the last number. It should be incremented.
0015
0016 ### Examples
0017
0018 Page 0 will have {a41e1438-0aee-46d1-8714-2a284634df77}_background_0.jpg as background
0019 Page 1 will have {a41e1438-0aee-46d1-8714-2a284634df77}_background_1.jpg as background
0020
0021 ## Number of character:
0022
0023 characterCount: \<int>
0024
0025 If the characterCount is zero that means this charactersheet describes only the structure of character sheet. A rcs file with no character is useless in Rolisteam. But you can add character in it with rcse.
0026
0027 ## Array of characters
0028
0029 A character is defined by the following fields:
0030
0031 * **idSheet**: \<string> uuid
0032 * **name**: \<string> name of the character
0033 * **values**: \<json object>
0034
0035 The values object has a key for each field defined in the data > items key.
0036 each key is defining the value for this specific field for this character.
0037
0038 example:
0039 ```
0040 "values": {
0041                 "id_1": {
0042                     "formula": "",
0043                     "id": "id_1",
0044                     "label": "name",
0045                     "readonly": false,
0046                     "type": "field",
0047                     "typefield": 0,
0048                     "value": "Ruth Sullivan"
0049                 }
0050           }
0051 ```
0052
0053 A value is a jsonobject with those keys:
0054
0055 * formula: \<string> eg: "=4+5" It should begin with '='
0056 * id: \<string> no space, no special caracter, no uppercase. Same as the key of jsonobject
0057 * label: \<string> an easy way to reference the field
0058 * readonly: \<bool> if true, no player can change the value of this field only the GM.
0059 * type: \<string> always set at field
0060 * typefield: \<int> : 0 => TextInput, 1 => TextField, 2=> TextArea, 3=> Select, 4=> Checkbox, 6=>Image, 7=>button
0061 * value: \<string>
0062
0063
0064
0065 ## Information about fields
0066
0067 the data key is an object called Section.
0068 A section may have many fields or subsections.
0069 A subsection is a section.
0070
0071 ## Section definition
0072
0073 A section is defined by three informations.
0074 * name : name of the section
0075 * type : always set at "Section"
0076 * items : an array of fields.
0077
0078
0079 ## Field definition:
0080
0081 * bgcolor: \<color>
0082 * border: \<int> // 0 no border, 16 border all around
0083 * clippedText: \<bool>
0084 * font: \<font definition (eg: Ubuntu,11,-1,5,50,0,0,0,0,0)>
0085 * formula: \<string eg: "=4+5"> It should begin with '='
0086 * height: \<real>
0087 * id: \<string> no space, no special caracter, no uppercase.
0088 * label: \<string> name of the field better readability
0089 * page: \<int> page where the field is visible
0090 * textalign: \<int> // 1=> 2=>
0091 * textColor: \<color>
0092 * type: \<string> // always set at field
0093 * typefield: \<int> : 0 => TextInput, 1 => TextField, 2=> TextArea, 3=> Select, 4=> Checkbox, 6=>Image, 7=>button
0094 * value: \<value>
0095 * values: \<array of values>
0096 * width: \<real>
0097 * x: \<real>
0098 * y: \<real>
0099
0100 ### Color
0101
0102 The color type is defined like this:
0103 ```
0104 {
0105       "a": 255,
0106       "b": 0,
0107       "g": 0,
0108       "r": 0
0109 }
0110 ```
0111 A is the alpha channel. 0 means transparent color.
0112 b is the blue channel.
0113 g is the green channel.
0114 r is the red channel.
0115
0116
0117 ## QML
0118
0119 To make your charactersheet directly working on rolisteam, you must generate the qml and store it in the json file under the key: "qml".
0120
0121 To generate QML code, you must create the structure of the QML:
0122
0123 If your charactersheet has background image:
0124
0125 ```qml
0126 import QtQuick 2.4
0127 import "qrc:/resources/qml/"
0128 Item {
0129    id:root
0130        focus: true
0131        property int page: 0
0132        property int maxPage: __pageMax__
0133        onPageChanged: {
0134            page=page>maxPage ? maxPage : page<0 ? 0 : page
0135        }
0136        Keys.onLeftPressed: --page
0137        Keys.onRightPressed: ++page
0138        signal rollDiceCmd(string cmd)
0139        MouseArea {
0140             anchors.fill:parent
0141             onClicked: root.focus = true
0142         }
0143
0144            Image {
0145                id:imagebg
0146                property real iratio : ___ratio___
0147                property real iratiobis : ___ratioBis___
0148                property real realscale: width/ ___Image_Width___
0149                width:(parent.width>parent.height*iratio)?iratio*parent.height:parent.width
0150                height:(parent.width>parent.height*iratio)?parent.height:iratiobis*parent.width
0151                source: "image://rcs/__key___background_%1.jpg".arg(root.page)
0152                __LIST_OF_FIELD__
0153
0154           }
0155
0156   }
0157   ```
0158
0159 If your charactersheet has no background image:
0160
0161 ```qml
0162 import QtQuick 2.4
0163 import "qrc:/resources/qml/"
0164 Item {
0165    id:root
0166        focus: true
0167        property int page: 0
0168        property int maxPage: __pageMax__
0169        onPageChanged: {
0170            page=page>maxPage ? maxPage : page<0 ? 0 : page
0171        }
0172        Keys.onLeftPressed: --page
0173        Keys.onRightPressed: ++page
0174        signal rollDiceCmd(string cmd)
0175        MouseArea {
0176             anchors.fill:parent
0177             onClicked: root.focus = true
0178         }
0179
0180         property real realscale: 1
0181        __LIST_OF_FIELD__
0182   }
0183 ```
0184
0185
0186 All of those variables must be defined into the generated qml code.
0187 * \_\_pageMax__ is page count
0188 * \_\_key__ is the key of all background images
0189 * \_\_LIST_OF_FIELD__ is the place where the code of all field must be added.
0190
0191
0192 ## Generate Fields
0193
0194 ### TEXTFIELD
0195
0196 ```qml
0197 TextFieldField {
0198         id: ___id__
0199         text: __id__.value
0200         textColor: __color_text__
0201         x: __posX__*parent.realscale
0202         clippedText: true or false
0203         y: __posY__*parent.realscale
0204         width: __width__*parent.realscale
0205         height: __height__*parent.realscale
0206         color: __bgColor__
0207         visible: root.page === __page__ ? true : false
0208         readOnly: __id__.readOnly
0209         font.family: __font_family__
0210         font.bold: true or false
0211         font.italic: true or false
0212         font.underline: true or false
0213         font.pointSize: __font_size__
0214         font.overline: true or false
0215         font.strikeout: true or false
0216         hAlign: TextInput.AlignTop or TextInput.AlignVCenter or TextInput.AlignBottom
0217         vAlign: TextInput.AlignRight or TextInput.AlignHCenter or TextInput.AlignLeft
0218         onTextChanged: {
0219             __id__.value = text
0220         }
0221
0222
0223 }
0224 ```
0225
0226 ### TEXTINPUT
0227
0228 ```qml
0229 TextInputField {
0230         id: ___id__
0231         text: __id__.value
0232         textColor: __color_text__
0233         x: __posX__*parent.realscale
0234         clippedText: true or false
0235         y: __posY__*parent.realscale
0236         width: __width__*parent.realscale
0237         height: __height__*parent.realscale
0238         color: __bgColor__
0239         visible: root.page === __page__ ? true : false
0240         readOnly: __id__.readOnly
0241         font.family: __font_family__
0242         font.bold: true or false
0243         font.italic: true or false
0244         font.underline: true or false
0245         font.pointSize: __font_size__
0246         font.overline: true or false
0247         font.strikeout: true or false
0248         onTextChanged: {
0249             __id__.value = text
0250         }
0251
0252 }
0253 ```
0254
0255 ### TEXTAREA
0256
0257 ```qml
0258 TextAreaField {
0259         id: ___id__
0260         text: __id__.value
0261         textColor: __color_text__
0262         x: __posX__*parent.realscale
0263         clippedText: true or false
0264         y: __posY__*parent.realscale
0265         width: __width__*parent.realscale
0266         height: __height__*parent.realscale
0267         color: __bgColor__
0268         visible: root.page === __page__ ? true : false
0269         readOnly: __id__.readOnly
0270         font.family: __font_family__
0271         font.bold: true or false
0272         font.italic: true or false
0273         font.underline: true or false
0274         font.pointSize: __font_size__
0275         font.overline: true or false
0276         font.strikeout: true or false
0277         onTextChanged: {
0278             __id__.value = text
0279         }
0280 }
0281 ```
0282
0283
0284 ### CHECKBOX
0285
0286 ```qml
0287 CheckBoxField {
0288         id: ___id__
0289         text: __id__.value
0290         textColor: __color_text__
0291         x: __posX__*parent.realscale
0292         clippedText: true or false
0293         y: __posY__*parent.realscale
0294         width: __width__*parent.realscale
0295         height: __height__*parent.realscale
0296         color: __bgColor__
0297         visible: root.page === __page__ ? true : false
0298         readOnly: __id__.readOnly
0299         onTextChanged: {
0300             __id__.value = text
0301         }
0302
0303
0304 }
0305 ```
0306
0307
0308 ### SELECT
0309 ```qml
0310 SelectField {
0311         id: ___id__
0312         availableValues:["value1", "value2", "value3"]
0313         currentIndex: combo.find(text)
0314         onCurrentIndexChanged:{
0315                 if(count>0)
0316                 {
0317                         __id__.value = currentText
0318                 }
0319         }
0320         text: __id__.value
0321         textColor: __color_text__
0322         x: __posX__*parent.realscale
0323         clippedText: true or false
0324         y: __posY__*parent.realscale
0325         width: __width__*parent.realscale
0326         height: __height__*parent.realscale
0327         color: __bgColor__
0328         visible: root.page === __page__ ? true : false
0329         readOnly: __id__.readOnly
0330 }
0331 ```
0332
0333 ### IMAGE
0334 ```qml
0335 ImageField {
0336         id: ___id__
0337         text: __id__.value
0338         textColor: __color_text__
0339         x: __posX__*parent.realscale
0340         clippedText: true or false
0341         y: __posY__*parent.realscale
0342         width: __width__*parent.realscale
0343         height: __height__*parent.realscale
0344         color: __bgColor__
0345         visible: root.page === __page__ ? true : false
0346         readOnly: __id__.readOnly
0347         onTextChanged: {
0348             __id__.value = text
0349         }
0350 }
0351 ```
0352
0353 ### BUTTON
0354 ```qml
0355 DiceButton {
0356         id: ___id__
0357         text: __id__.label
0358         textColor: __color_text__
0359         x: __posX__*parent.realscale
0360         clippedText: true or false
0361         y: __posY__*parent.realscale
0362         width: __width__*parent.realscale
0363         height: __height__*parent.realscale
0364         color: __bgColor__
0365         visible: root.page === __page__ ? true : false
0366         readOnly: __id__.readOnly
0367         font.family: __font_family__
0368         font.bold: true or false
0369         font.italic: true or false
0370         font.underline: true or false
0371         font.pointSize: __font_size__
0372         font.overline: true or false
0373         font.strikeout: true or false
0374         onClicked:rollDiceCmd(__id__.value)
0375 }
0376 ```
0377
0378 ## Details of field
0379 * \_\_id__ : id of the field, in rcse it is generated on this scheme: id_[0-9]+. It allows to refer to dynamic data inside the model.
0380 * \_\_color_text__ : #RRGGBB or #AARRGGBB or name from https://www.w3.org/TR/SVG/types.html#ColorKeywords
0381 * \_\_posX__ : position on X axis of the field
0382 * \_\_posY__ : position on Y axis of the field
0383 * \_\_width__ : width of the current field
0384 * \_\_height__ : height of the current field
0385 * \_\_bgColor__ : #RRGGBB or #AARRGGBB or name from https://www.w3.org/TR/SVG/types.html#ColorKeywords
0386 * \_\_page__ : define on which page this field must be displayed
0387 * \_\_font_family__ : http://doc.qt.io/qt-5/qfont.html#toString
0388 * \_\_font_size__ : size in point of the font
0389