| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| gamedev:dnp [2022/07/16 16:37] – [Reliable message] dragonlord | gamedev:dnp [2024/03/14 16:33] (current) – dragonlord |
|---|
| |
| <WRAP center round important 60%> | <WRAP center round important 60%> |
| Network protocols typically use //Network Byte Order// as defined by the TCP standard which is //Big Endian//. The message writing and reading of DNP is implemented to match Drag[en]gine [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecBaseFileReader.html|File Reader/Writer]] system. This allows all data written by game scripts to be stored to file, written to memory and transmitted across the network without changing the data. Since this system uses //Little Endian// DNP uses //Little Endian// too. Hence throughout this specification //Little Endian// byte ordering is used unless marked otherwise. | Network protocols typically use //Network Byte Order// as defined by the TCP standard which is //Big Endian//. The message writing and reading of DNP is implemented to match Drag[en]gine #@LinkApiDocDE2_HTML~classdecBaseFileReader.html,File Reader/Writer~@# system. This allows all data written by game scripts to be stored to file, written to memory and transmitted across the network without changing the data. Since this system uses //Little Endian// DNP uses //Little Endian// too. Hence throughout this specification //Little Endian// byte ordering is used unless marked otherwise. |
| </WRAP> | </WRAP> |
| |
| ====== Data Types ====== | ====== Data Types ====== |
| |
| For message writing and reading the same [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecBaseFileWriter.html|file writer]] system is used as for file and memory data writing and reading. This ensures any data written in the game engine (no matter if saved to files, persisted to memory or transmitted across the network) is using the same binary format and is interchangeable. You can save data to files and transmit the file data as-is across the network and read it successfully on the other side. | For message writing and reading the same #@LinkApiDocDE2_HTML~classdecBaseFileWriter.html,file writer~@# system is used as for file and memory data writing and reading. This ensures any data written in the game engine (no matter if saved to files, persisted to memory or transmitted across the network) is using the same binary format and is interchangeable. You can save data to files and transmit the file data as-is across the network and read it successfully on the other side. |
| |
| The following data types are supported (names match [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecBaseFileReader.html|decBaseFileReader]]: | The following data types are supported (names match #@LinkApiDocDE2_HTML~classdecBaseFileReader.html,decBaseFileReader~@#: |
| |
| ^ Data type ^ Length ^ Description ^ | ^ Data type ^ Length ^ Description ^ |
| | Float | 4 bytes | 32-bit floating point value. | | | Float | 4 bytes | 32-bit floating point value. | |
| | Double | 8 bytes | 64-bit floating point value. | | | Double | 8 bytes | 64-bit floating point value. | |
| | String8 | 1 + length bytes | Unsigned 8-bit value storing the length of UTF-8 encoded string followed by "length" unsigned 8-bit integer characters. [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecString.html|String]] can not be longer than 255 characters (UTF8 encoded). | | | String8 | 1 + length bytes | Unsigned 8-bit value storing the length of UTF-8 encoded string followed by "length" unsigned 8-bit integer characters. #@LinkApiDocDE2_HTML~classdecString.html,String~@# can not be longer than 255 characters (UTF8 encoded). | |
| | String16 | 2 + length bytes | Unsigned 16-bit value storing the length of UTF-8 encoded string followed by "length" unsigned 8-bit integer characters. [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecString.html|String]] can not be longer than 65'535 characters (UTF8 encoded). | | | String16 | 2 + length bytes | Unsigned 16-bit value storing the length of UTF-8 encoded string followed by "length" unsigned 8-bit integer characters. #@LinkApiDocDE2_HTML~classdecString.html,String~@# can not be longer than 65'535 characters (UTF8 encoded). | |
| | Vector | 12 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecVector.html|vector]] with 32-bit floating point values for each component stored in order X, Y then Z. | | | Vector | 12 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecVector.html,vector~@# with 32-bit floating point values for each component stored in order X, Y then Z. | |
| | Vector2 | 8 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecVector2.html|vector]] with 32-bit floating point values for each component stored in order X then Y. | | | Vector2 | 8 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecVector2.html,vector~@# with 32-bit floating point values for each component stored in order X then Y. | |
| | Quaternion | 16 bytes | 4-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecQuaternion.html|quaternion]] with 32-bit floating point values for each component stored in order X, Y, Z then W. | | | Quaternion | 16 bytes | 4-Component #@LinkApiDocDE2_HTML~classdecQuaternion.html,quaternion~@# with 32-bit floating point values for each component stored in order X, Y, Z then W. | |
| | Point | 8 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint.html|point]] with 32-bit signed integer values for each component stored in order X then Y. | | | Point | 8 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecPoint.html,point~@# with 32-bit signed integer values for each component stored in order X then Y. | |
| | Point3 | 12 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint3.html|point]] with 32-bit signed integer values for each component stored in order X, Y then Z. | | | Point3 | 12 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecPoint3.html,point~@# with 32-bit signed integer values for each component stored in order X, Y then Z. | |
| | DVector | 24 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecDVector.html|vector]] with 64-bit floating point values for each component stored in order X, Y then Z. | | | DVector | 24 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecDVector.html,vector~@# with 64-bit floating point values for each component stored in order X, Y then Z. | |
| | Color | 16 bytes | 4-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecColor.html|color]] with 32-bit floating point values for each component stored in order R, G, B then A. | | | Color | 16 bytes | 4-Component #@LinkApiDocDE2_HTML~classdecColor.html,color~@# with 32-bit floating point values for each component stored in order R, G, B then A. | |
| | Color3 | 12 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecColor.html|color]] with 32-bit floating point values for each component stored in order R, G then B. | | | Color3 | 12 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecColor.html,color~@# with 32-bit floating point values for each component stored in order R, G then B. | |
| |
| ====== State Value Data Types ====== | ====== State Value Data Types ====== |
| | Float32 | ''9'' | 4 bytes | 32-bit floating point value. | | | Float32 | ''9'' | 4 bytes | 32-bit floating point value. | |
| | Float64 | ''10'' | 8 bytes | 64-bit floating point value. | | | Float64 | ''10'' | 8 bytes | 64-bit floating point value. | |
| | String | ''11'' | N bytes | UTF8 encoded [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecString.html|String]] of variable length. | | | String | ''11'' | N bytes | UTF8 encoded #@LinkApiDocDE2_HTML~classdecString.html,String~@# of variable length. | |
| | Data | ''12'' | N bytes | Arbitrary data stored as UInt8 values. | | | Data | ''12'' | N bytes | Arbitrary data stored as UInt8 values. | |
| | Point2S8 | ''13'' | 2 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint.html|point]] with signed 8-bit signed integer values for each component stored in order X then Y. | | | Point2S8 | ''13'' | 2 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecPoint.html,point~@# with signed 8-bit signed integer values for each component stored in order X then Y. | |
| | Point2U8 | ''14'' | 2 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint.html|point]] with unsigned 8-bit signed integer values for each component stored in order X then Y. | | | Point2U8 | ''14'' | 2 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecPoint.html,point~@# with unsigned 8-bit signed integer values for each component stored in order X then Y. | |
| | Point2S16 | ''15'' | 4 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint.html|point]] with signed 16-bit signed integer values for each component stored in order X then Y. | | | Point2S16 | ''15'' | 4 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecPoint.html,point~@# with signed 16-bit signed integer values for each component stored in order X then Y. | |
| | Point2U16 | ''16'' | 4 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint.html|point]] with unsigned 16-bit signed integer values for each component stored in order X then Y. | | | Point2U16 | ''16'' | 4 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecPoint.html,point~@# with unsigned 16-bit signed integer values for each component stored in order X then Y. | |
| | Point2S32 | ''17'' | 8 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint.html|point]] with signed 32-bit signed integer values for each component stored in order X then Y. | | | Point2S32 | ''17'' | 8 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecPoint.html,point~@# with signed 32-bit signed integer values for each component stored in order X then Y. | |
| | Point2U32 | ''18'' | 8 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint.html|point]] with unsigned 32-bit signed integer values for each component stored in order X then Y. | | | Point2U32 | ''18'' | 8 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecPoint.html,point~@# with unsigned 32-bit signed integer values for each component stored in order X then Y. | |
| | Point2S64 | ''19'' | 16 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint.html|point]] with signed 64-bit signed integer values for each component stored in order X then Y. | | | Point2S64 | ''19'' | 16 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecPoint.html,point~@# with signed 64-bit signed integer values for each component stored in order X then Y. | |
| | Point2U64 | ''20'' | 16 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint.html|point]] with unsigned 64-bit signed integer values for each component stored in order X then Y. | | | Point2U64 | ''20'' | 16 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecPoint.html,point~@# with unsigned 64-bit signed integer values for each component stored in order X then Y. | |
| | Point3S8 | ''21'' | 3 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint3.html|point]] with signed 8-bit signed integer values for each component stored in order X, Y then Z. | | | Point3S8 | ''21'' | 3 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecPoint3.html,point~@# with signed 8-bit signed integer values for each component stored in order X, Y then Z. | |
| | Point3U8 | ''22'' | 3 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint3.html|point]] with unsigned 8-bit signed integer values for each component stored in order X, Y then Z. | | | Point3U8 | ''22'' | 3 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecPoint3.html,point~@# with unsigned 8-bit signed integer values for each component stored in order X, Y then Z. | |
| | Point3S16 | ''23'' | 6 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint3.html|point]] with signed 16-bit signed integer values for each component stored in order X, Y then Z. | | | Point3S16 | ''23'' | 6 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecPoint3.html,point~@# with signed 16-bit signed integer values for each component stored in order X, Y then Z. | |
| | Point3U16 | ''24'' | 6 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint3.html|point]] with unsigned 16-bit signed integer values for each component stored in order X, Y then Z. | | | Point3U16 | ''24'' | 6 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecPoint3.html,point~@# with unsigned 16-bit signed integer values for each component stored in order X, Y then Z. | |
| | Point3S32 | ''25'' | 3 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint3.html|point]] with signed 32-bit signed integer values for each component stored in order X, Y then Z. | | | Point3S32 | ''25'' | 3 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecPoint3.html,point~@# with signed 32-bit signed integer values for each component stored in order X, Y then Z. | |
| | Point3U32 | ''26'' | 3 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint3.html|point]] with unsigned 32-bit signed integer values for each component stored in order X, Y then Z. | | | Point3U32 | ''26'' | 3 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecPoint3.html,point~@# with unsigned 32-bit signed integer values for each component stored in order X, Y then Z. | |
| | Point3S64 | ''27'' | 3 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint3.html|point]] with signed 64-bit signed integer values for each component stored in order X, Y then Z. | | | Point3S64 | ''27'' | 3 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecPoint3.html,point~@# with signed 64-bit signed integer values for each component stored in order X, Y then Z. | |
| | Point3U64 | ''28'' | 3 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecPoint3.html|point]] with unsigned 64-bit signed integer values for each component stored in order X, Y then Z. | | | Point3U64 | ''28'' | 3 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecPoint3.html,point~@# with unsigned 64-bit signed integer values for each component stored in order X, Y then Z. | |
| | Vector2F16 | ''29'' | 4 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecVector2.html|vector]] with 16-bit floating point values for each component stored in order X then Y. | | | Vector2F16 | ''29'' | 4 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecVector2.html,vector~@# with 16-bit floating point values for each component stored in order X then Y. | |
| | Vector2F32 | ''30'' | 8 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecVector2.html|vector]] with 32-bit floating point values for each component stored in order X then Y. | | | Vector2F32 | ''30'' | 8 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecVector2.html,vector~@# with 32-bit floating point values for each component stored in order X then Y. | |
| | Vector2F64 | ''31'' | 16 bytes | 2-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecVector2.html|vector]] with 64-bit floating point values for each component stored in order X then Y. | | | Vector2F64 | ''31'' | 16 bytes | 2-Component #@LinkApiDocDE2_HTML~classdecVector2.html,vector~@# with 64-bit floating point values for each component stored in order X then Y. | |
| | Vector3F16 | ''32'' | 6 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecVector.html|vector]] with 16-bit floating point values for each component stored in order X, Y then Z. | | | Vector3F16 | ''32'' | 6 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecVector.html,vector~@# with 16-bit floating point values for each component stored in order X, Y then Z. | |
| | Vector3F32 | ''33'' | 12 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecVector.html|vector]] with 32-bit floating point values for each component stored in order X, Y then Z. | | | Vector3F32 | ''33'' | 12 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecVector.html,vector~@# with 32-bit floating point values for each component stored in order X, Y then Z. | |
| | Vector3F64 | ''34'' | 24 bytes | 3-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecVector.html|vector]] with 64-bit floating point values for each component stored in order X, Y then Z. | | | Vector3F64 | ''34'' | 24 bytes | 3-Component #@LinkApiDocDE2_HTML~classdecVector.html,vector~@# with 64-bit floating point values for each component stored in order X, Y then Z. | |
| | QuaternionF16 | ''35'' | 8 bytes | 4-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecQuaternion.html|quaternion]] with 16-bit floating point values for each component stored in order X, Y, Z then W. | | | QuaternionF16 | ''35'' | 8 bytes | 4-Component #@LinkApiDocDE2_HTML~classdecQuaternion.html,quaternion~@# with 16-bit floating point values for each component stored in order X, Y, Z then W. | |
| | QuaternionF32 | ''36'' | 16 bytes | 4-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecQuaternion.html|quaternion]] with 32-bit floating point values for each component stored in order X, Y, Z then W. | | | QuaternionF32 | ''36'' | 16 bytes | 4-Component #@LinkApiDocDE2_HTML~classdecQuaternion.html,quaternion~@# with 32-bit floating point values for each component stored in order X, Y, Z then W. | |
| | QuaternionF64 | ''37'' | 32 bytes | 4-Component [[https://developer.dragondreams.ch/docs/dragengine/latest/classdecQuaternion.html|quaternion]] with 64-bit floating point values for each component stored in order X, Y, Z then W. | | | QuaternionF64 | ''37'' | 32 bytes | 4-Component #@LinkApiDocDE2_HTML~classdecQuaternion.html,quaternion~@# with 64-bit floating point values for each component stored in order X, Y, Z then W. | |
| |
| ====== Reliable Communication ====== | ====== Reliable Communication ====== |
| Send by client or server or server to client. used to send an unreliable message to the other communication partner. Unreliable messages are used for frequently send messages. They are not acknowledged and thus can be possibly lost. Furthermore they can be delivered to the application in any order. Applications have to use unreliable messages only if the loss of information can be compensated, for example by receiving another update in regular intervals. | Send by client or server or server to client. used to send an unreliable message to the other communication partner. Unreliable messages are used for frequently send messages. They are not acknowledged and thus can be possibly lost. Furthermore they can be delivered to the application in any order. Applications have to use unreliable messages only if the loss of information can be compensated, for example by receiving another update in regular intervals. |
| |
| <WRAP center round info 60%> | Messages should be of short length. No explicit fragmenting of message content is done. This is left for the underlying communication channel. If a message is not fully received it has to be considered lost. The exact message size fitting into one communication channel package depends on the communication channel and is often not detectable. As a rule of thumb on IPv4 a package size of 1200 (conservative 540) can be expected to be transmitted in one package. |
| Messages should be of short length. No explicit fragmenting of message content is done. This is left for the underlying communication channel. If a message is not fully received it has to be considered lost. The exact message size fitting into one communication channel package depends on the communication channel and is often not detectable. As a rule of thumb on IPv4 a message of 520 bytes length can be expected to be transmitted in one package. | |
| </WRAP> | |
| |
| The command has this format: | The command has this format: |
| Send by client or server or from server to client. Used to send a reliable message to the other communication partner. Reliable messages are used for infrequent send messages of high importance. They are acknowledged and guaranteed to be received. Furthermore they are guaranteed to be delivered to the application in the order they have been send. Applications have to use reliable messages only if loss of information can not be compensated. | Send by client or server or from server to client. Used to send a reliable message to the other communication partner. Reliable messages are used for infrequent send messages of high importance. They are acknowledged and guaranteed to be received. Furthermore they are guaranteed to be delivered to the application in the order they have been send. Applications have to use reliable messages only if loss of information can not be compensated. |
| |
| Messages should be of short length. No explicit fragmenting of message content is done. This is left for the underlying communication channel. If a message is not fully received it has to be considered lost. The exact message size fitting into one communication channel package depends on the communication channel and is often not detectable. As a rule of thumb on IPv4 a message of 520 bytes length can be expected to be transmitted in one package. | Messages should be of short length. No explicit fragmenting of message content is done. This is left for the underlying communication channel. If a message is not fully received it has to be considered lost. The exact message size fitting into one communication channel package depends on the communication channel and is often not detectable. As a rule of thumb on IPv4 a package size of 1200 (conservative 540) can be expected to be transmitted in one package. |
| |
| The command has this format: | The command has this format: |
| Send by client to server or server to client. Used to [[#network_state|link a local network state]] to the other side. Both client and server can send link requests to the other side. It is up to the application to decide if a link request is accepted or declined. | Send by client to server or server to client. Used to [[#network_state|link a local network state]] to the other side. Both client and server can send link requests to the other side. It is up to the application to decide if a link request is accepted or declined. |
| |
| Link messages should be of short length. No explicit fragmenting of message content is done. This is left for the underlying communication channel. If a message is not fully received it has to be considered lost. The exact message size fitting into one communication channel package depends on the communication channel and is often not detectable. As a rule of thumb on IPv4 a message of 520 bytes length can be expected to be transmitted in one package. This size is reduced by the count of value data send along the message. | Messages should be of short length. No explicit fragmenting of message content is done. This is left for the underlying communication channel. If a message is not fully received it has to be considered lost. The exact message size fitting into one communication channel package depends on the communication channel and is often not detectable. As a rule of thumb on IPv4 a package size of 1200 (conservative 540) can be expected to be transmitted in one package. This size is reduced by the count of value data send along the message. |
| |
| The command has this format: | The command has this format: |
| Send by client to server or server to client. Used to update a remote state. Client or server is only allowed to send a state update if it has a read-write state. This is the case if the client or server linked the state to other sides or it received a state with read-write capability. | Send by client to server or server to client. Used to update a remote state. Client or server is only allowed to send a state update if it has a read-write state. This is the case if the client or server linked the state to other sides or it received a state with read-write capability. |
| |
| The command contains one or more values to update which do not have to be of the same state. The sender is not required to update all values with one command send. The sender decides how many values it includes in the command and when it updates the values. In general the sender has to update state changes as fast as possible. The data type range and precision information assigned to values has to be used to send updates only if necessary. For example a floating point value with 0.1 precision should only send an update if the value set by the application deviates more than 0.1 from the last known value. The application sets the precision according to needs. Optionally the sender can update state values if they have recently changed but not more than their precision requires. | The command contains one or more values to update which do not have to be of the same state. The sender is not required to update all values with one command send. The sender decides how many values it includes in the command and when it updates the values. In general the sender has to update state changes as fast as possible. The data type range and precision information assigned to values has to be used to send updates only if necessary. For example a floating point value with 0.1 precision should only send an update if the value set by the application deviates more than 0.1 from the last known value. The application sets the precision according to needs. Optionally the sender can update state values if they have recently changed but not more than their precision requires. This can be used as a kind of "keep-alive". In this case //LinkCount// is ''0''. |
| |
| If the receives values change enough (according to the same rules as sending them) the application has to be send notification for each changed value. | If the receives values change enough (according to the same rules as sending them) the application has to be send notification for each changed value. |
