diff --git a/source/main/resources/truck_fileformat/ReadMe.txt b/source/main/resources/truck_fileformat/ReadMe.txt index 35956cc3bd..b8eed0954f 100644 --- a/source/main/resources/truck_fileformat/ReadMe.txt +++ b/source/main/resources/truck_fileformat/ReadMe.txt @@ -1,169 +1,92 @@ -================================================================================ - Softbody definition file format "Truck" specification - Project Rigs of Rods (http://www.rigsofrods.org) -================================================================================ +Truck file format (technical spec) +================================== -INTRO -===== - -"Truck" is a human-friendly custom format for defining softbody game entities -- trucks, cars, boats, airplanes, loads and fixed objects. - -VERSION -======= +Truck is a human friendly text format created and used by Rigs of Rods (www.rigsofrods.org). +Find user documentation at http://docs.rigsofrods.org/vehicle-creation/fileformat-truck. This spec applies to Rigs of Rods version 0.4.5 and further. -This spec covers all prior versions of the format: 1, 2, 3, 450 +This spec covers all prior versions of the format: 1, 2, 3, 450 (discontinued) +See also 'fileformatversion'. -SYNTAX -====== +Syntax +------ -The format is line-based. +The format is line-based. Empty lines and comments are skipped. -Lines starting with semicolon ";" or slash "/" are comments. -NOTE: The "/" comments were documented as "//", but the parser -only ever checked the first character. -IMPORTANT: Comments MUST be on separate line! Trailing comments are not supported. +Lines starting with semicolon ";" or slash "/" (documented as '//') are comments. +Placing ';' or '/' anywhere else will not be considered a comment, but parsed as regular data! -There are several syntaxes for parsing a line: +Each line is treated as values separated by separators. +Possible separators: space, tabulator, comma ",", colon ":" or pipe "|". +Multiple separators in a row (even if different from each other) are treated as one. - Default - The most usual and relaxed one - Entire line is treated as values separated by separators. - Possible separators: space, tabulator, comma ",", colon ":" or pipe "|". - Whitespace and "," are well known, others weren't documented as generic. - Multiple separators in a row squash into one, i.e. this is a valid line: - set_beam_defaults |,| -1 -1 ,,,,, -1, -1 +Element types +------------- - Keyword-space-CSV - More complex sections - Line consists of: keyword, space (separator), CSV (comma sep. values) - The keyword is cut away, the rest is split along ",". +Title + The first non-comment & non-empty of the file is a title. - Keyword-CSV - Like above, except the space is optional. - - CSV - Classic comma-separated-values. Only separator is ',' - - CommaSpaceSV - Separators are space or comma. - -The format consists of these elements: - - Title - The first line of the file is a title. - - Inline-section - Example: author. - Has a keyword at start of line and data follow on the same line. - Following lines do not belong to any section. - - Block-section - Example: nodes. - Begins with a line containing nothing but a keyword. - All subsequent lines belong to it until another - section (any type) is encountered or module closed. - - Animator-section - Keyword: `animators` - Works like block-section, except lines have special syntax. - See chapter "SECTION ANIMATORS" for details. - - Multiline-section - Single instance: "description/end_description". - Begins with a line containing nothing but "description". - Ends with a line containing nothing but "end_description". - All lines in between belong to it. Keywords inside it are ignored. - Subsequent lines belong to no section. - - Multiline-comment - Single instance: "comment/end_comment". - Begins with a line containing nothing but "description". - Ends with a line containing nothing but "end_description". - All lines in between belong to it. Keywords inside it are ignored. - Can appear inside any block-section, does not affect it. - - Directive - Example: set_beam_defaults - Consists of keyword at the beginning of the line and data on the same line. - May perform various task, usualy set global attributes or change - behavior of the parsing. - Directive may appear in any block-section. - - Module - Begins with a line containing nothing but "section". - Ends with a line containing nothing but "end_section". - A chunk of file which represents an optional modification of the vehicle. - See below for details. - -COMPATIBILITY -============= - -Since RoR v0.4.5, all elements fully support named nodes. -In previous RoR versions, support was partial and undocumented. +Inline-section + Example: author. + Has a keyword at start of line and data follow on the same line. + Following lines do not belong to any section. -Since RoR v0.4.5 the order of elements in truckfile doesn't matter. -The spawn process follows a pre-defined order of elements. -Exceptions: - add_animation (must be after section 'prop') - flexbody_camera_mode (must be after section 'flexbody') -In previous versions, the order of elements defined the final result -and some combinations resulted in a crash. +Block-section + Example: nodes. + Begins with a line containing nothing but a keyword. + All subsequent lines belong to it until another + section (any type) is encountered or module closed. + Some may have special syntax, i.e. 'animators' -Since v0.4.5, all elements can be modularized using 'section' keyword, except: - author - description - disabledefaultsounds - enable_advanced_deformation - fileformatversion - fileinfo - forwardcommands - guid - hideInChooser - importcommands - lockgroup_default_nolock - minimass - rescuer - rollon -In previous versions, this was undocumented. - -Since v0.4.5, keyword 'sectionconfig' is no longer necessary and parser silently ignores it. -Modules are created as keyword 'section' is encountered. - -Since v0.4.5 sections 'nodes' and 'nodes2' both support named nodes. - -Since v0.4.5 sections 'commands' & 'commands2' are unified. -The only difference is in compress & expand ratios. -Both support the same flags and can use multiple flags at once. - -Since v0.4.5 subsection 'flexbodies'/'forset' supports named nodes. -However, ranges are only supported for nubered nodes. - -Since v0.4.5 the 'end' keyword is no longer needed. Parser silently ignores it. -In previous versions, it was critical - without it, RoR crashed. - -Since v0.4.5 the optional param 'wings/control_type' now has default 'n' -Old parser had no default, though the param is optional. - -DOCUMENTATION -============= - -See http://docs.rigsofrods.org/vehicle-creation/fileformat-truck +Multiline-description + Single instance: "description/end_description". + Begins with a line containing nothing but "description". + Ends with a line containing nothing but "end_description". + All lines in between belong to it. Keywords inside it are ignored. + Subsequent lines belong to no section. + +Multiline-comment + Single instance: "comment/end_comment". + Begins with a line containing nothing but "description". + Ends with a line containing nothing but "end_description". + All lines in between belong to it. Keywords inside it are ignored. + Can appear inside any block-section, does not affect it. + +Directive + Example: set_beam_defaults + Consists of keyword at the beginning of the line and data on the same line. + May perform various task, usualy set global attributes or change + behavior of the parsing. + Directive may appear in any block-section. + +Modularity +---------- + +The elements can be grouped into modules. Each module must belong to one or more configurations. + +Directives 'sectionconfig' specify truck configurations the user can choose from. +Exactly one must be selected. If none, the first defined is used. +Syntax: "sectionconfig " + +A module begins with keyword "section". Syntax: + "section [ ...]" + where is unused number and config is a name specified in sectionconfig. +Module ends with keyword "end_section". + +List of elements +---------------- -Below is a list of all supported elements. -NOTE: All keywords are case insensitive, -the lettercase in this list corresponds to original documentation. +Order is alphabetical, lettercase matches original docs (parsing is insensitive). - NAME TYPE SYNTAX + NAME TYPE NOTES advdrag BLOCK - add_animation DIRECTIVE Keyword-Space-CSV + custom proc. - airbrakes BLOCK Default - animators ANIMATORS - AntiLockBrakes DIRECTIVE Keyword-CSV - author DIRECTIVE Default - axles BLOCK CSV + custom processing + add_animation DIRECTIVE Special syntax + airbrakes BLOCK + animators BLOCK Special syntax: values separated by comma, options separated by '|'. + AntiLockBrakes DIRECTIVE + author DIRECTIVE + axles BLOCK Special syntax beams BLOCK brakes BLOCK camerarail BLOCK @@ -174,9 +97,9 @@ the lettercase in this list corresponds to original documentation. commands2 BLOCK comment COMMENT contacters BLOCK - cruisecontrol BLOCK Default - description BLOCK - detacher_group DIRECTIVE Default + cruisecontrol BLOCK + description DESCRIPTION + detacher_group DIRECTIVE disabledefaultsounds DIRECTIVE enable_advanced_deformation DIRECTIVE engine BLOCK @@ -192,35 +115,35 @@ the lettercase in this list corresponds to original documentation. flares BLOCK flares2 BLOCK flexbodies BLOCK - flexbody_camera_mode DIRECTIVE Default + flexbody_camera_mode DIRECTIVE flexbodywheels BLOCK - forset INLINE Keyword-CSV + forset INLINE fusedrag BLOCK - globals BLOCK Default - guid DIRECTIVE Default + globals BLOCK + guid DIRECTIVE guisettings BLOCK - help BLOCK Default + help BLOCK hideInChooser DIRECTIVE hookgroup BLOCK hooks BLOCK hydros BLOCK importcommands DIRECTIVE - interaxles BLOCK CSV + custom processing + interaxles BLOCK Special syntax lockgroups BLOCK lockgroup_default_nolock DIRECTIVE managedmaterials BLOCK - materialflarebindings BLOCK Default + materialflarebindings BLOCK meshwheels BLOCK meshwheels2 BLOCK - minimass BLOCK Default - nodecollision BLOCK Default + minimass BLOCK + nodecollision BLOCK nodes BLOCK nodes2 BLOCK - particles BLOCK Default + particles BLOCK pistonprops BLOCK - prop_camera_mode DIRECTIVE Default + prop_camera_mode DIRECTIVE props BLOCK - railgroups BLOCK CSV + railgroups BLOCK rescuer DIRECTIVE rigidifiers BLOCK rollon DIRECTIVE @@ -229,32 +152,33 @@ the lettercase in this list corresponds to original documentation. rotators BLOCK rotators2 BLOCK screwprops BLOCK - sectionconfig MODULE + sectionconfig DIRECTIVE section MODULE - set_beam_defaults DIRECTIVE Default - set_beam_defaults_scale DIRECTIVE Default - set_collision_range DIRECTIVE Default - set_inertia_defaults DIRECTIVE Default - set_managedmaterials_options DIRECTIVE Default - set_node_defaults DIRECTIVE Default + set_beam_defaults DIRECTIVE + set_beam_defaults_scale DIRECTIVE + set_collision_range DIRECTIVE + set_default_minimass DIRECTIVE + set_inertia_defaults DIRECTIVE + set_managedmaterials_options DIRECTIVE + set_node_defaults DIRECTIVE set_shadows DIRECTIVE - set_skeleton_settings DIRECTIVE Default + set_skeleton_settings DIRECTIVE shocks BLOCK shocks2 BLOCK shocks3 BLOCK slidenode_connect_instantly DIRECTIVE - slidenodes BLOCK CommaSpaceSV + slidenodes BLOCK SlopeBrake BLOCK soundsources BLOCK soundsources2 BLOCK soundsources3 BLOCK - speedlimiter DIRECTIVE Default + speedlimiter DIRECTIVE submesh BLOCK - submesh_groundmodel DIRECTIVE Default + submesh_groundmodel DIRECTIVE ties BLOCK - torquecurve BLOCK CSV - TractionControl DIRECTIVE Keyword-Space-CSV - transfercase BLOCK Default + torquecurve BLOCK + TractionControl DIRECTIVE + transfercase BLOCK triggers BLOCK turbojets BLOCK turboprops BLOCK @@ -264,25 +188,79 @@ the lettercase in this list corresponds to original documentation. wheels2 BLOCK wings BLOCK +Compatibility +------------- + +Existing content places a lot of compatibility constraints on the format: +* Modules (section/end_section) must support: + - nodes2 with the same names in all modules (KickerRampV2.load) + - managedmaterials, props, help, soundsources, flexbodies, videocamera + - globals, author (many mods in archive - because of skins) + - flares (archive: BBV.zip - BBV95.truck) + - meshwheels, axles, commands2 (archive: Mercedess Actros 8x8_ampliroll.truck) + - engine, engoption, torquecurve (archive: ple002_SuperBus.truck, RockHopper.truck) + - //multiple sectionconfig names//(archive: ackermann_moving_trailer.zip) + - contacters (Betzi-tourliner.zip) + - TractionControl (archive: golf cart) + - brakes, nodes (archive: Blue&White-ScaniaR470TL.truck) + + +Since RoR v0.4.5, all elements fully support named nodes. +In previous RoR versions, support was partial and undocumented. + +Since RoR v0.4.5 the order of elements in truckfile doesn't matter. +The spawn process follows a pre-defined order of elements. +Exceptions: + add_animation (must be after section 'prop') + flexbody_camera_mode (must be after section 'flexbody') +In previous versions, the order of elements defined the final result +and some combinations resulted in a crash. + +Since v0.4.5, all elements can be modularized using 'section' keyword, except: + author + description + disabledefaultsounds + enable_advanced_deformation + fileformatversion + fileinfo + forwardcommands + guid + hideInChooser + importcommands + lockgroup_default_nolock + minimass + rescuer + rollon +In previous versions, this was undocumented. + +Since v0.4.5, keyword 'sectionconfig' is no longer necessary and parser silently ignores it. +Modules are created as keyword 'section' is encountered. + +Since v0.4.5 sections 'nodes' and 'nodes2' both support named nodes. + +Since v0.4.5 sections 'commands' & 'commands2' are unified. +The only difference is in compress & expand ratios. +Both support the same flags and can use multiple flags at once. + +Since v0.4.5 subsection 'flexbodies'/'forset' supports named nodes. +However, ranges are only supported for nubered nodes. + +Since v0.4.5 the 'end' keyword is no longer needed. Parser silently ignores it. +In previous versions, it was critical - without it, RoR crashed. + +Since v0.4.5 the optional param 'wings/control_type' now has default 'n' +Old parser had no default, though the param is optional. + +DOCUMENTATION +============= + + + SPECIAL SYNTAXES ================ -SECTION ANIMATOR ----------------- - -All whitespace is ignored. -Args 0 - 2 are processed normally. -Arg 3 is split along "|", valid elements are (written as regexes): - * /(throttle|rpm|aerotorq|aeropit|aerostatus)([12345678])/ ~ For example `throttle2` - * /shortlimit[:]+([.]*)/ ~ Value should be real number, example: `shortlimit: 0.5` - * /longlimit[:]+([.]*)/ ~ Value should be real number, example: `longlimit: 0.5` - * KEYWORD: vis,inv,airspeed,vvi, - altimeter100k,altimeter10k,altimeter1k, - aoa,flap,airbrake,roll,pitch,brakes,accel,clutch, - speedo,tacho,turbo,parking,shifterman1,shifterman2, - sequential,shifterlin,torque,difflock, - rudderboat,throttleboat + SECTION `FORSET` ----------------