User-friendly API abstraction on top of packets

[mkapal]

I wonder if it would make sense to add new methods to the InSim class, which would make it easier to send or receive packets without having to remember the exact packets and packet properties to send.

There is already a small abstraction like this - the InSim connection method. Instead of sending an IS_ISI packet, but you just call inSim.connect(). A similar approach could be taken with other packets.

Example 1 - sending a button

Problem:

• If you want to create a button with a type-in dialog including a caption, you must send the caption in the Text property delimited by zero-bytes: '\0Caption\0Text'.

Current API

inSim.send(new IS_BTN({
  ReqI: 1,
  L: 60,
  T: 4,
  W: 20,
  H: 5,
  TypeIn: 20,
  Text: '\0Caption\0Text',
}))

Proposed API

inSim.sendButton({
  requestId: 1,
  left: 60,
  top: 4,
  width: 20,
  height: 5,
  text: 'Text',
  typeIn: 20,
  caption: 'Caption',
})

Example 2 - sending a message or a command

Problem:

• If you want to send a command, you must send an IS_MST packet, otherwise you can decide between IS_MST and IS_MSX depending on the message length.
• If you want to send a message to a specific connection or a player, you must use IS_MTC.

Current API

// command
inSim.send(new IS_MST({
  Msg: '/spec Flame CZE',
}));

// short message (up to 64 characters)
inSim.send(new IS_MST({
  Msg: 'Hello!',
}));

// long message (up to 96 characters)
inSim.send(new IS_MSX({
  Msg: 'A very long chat message which is a bit longer than 64 characters',
}));

// message to connection
inSim.send(new IS_MTC({
  UCID: 4,
  Text: 'Hello, UCID 4!',
}));

// message to player
inSim.send(new IS_MTC({
  PLID: 6,
  Text: 'Hello, PLID 6!',
}));

Proposed API

There could be one method called sendMessage() or maybe just send() which would accept a text string:

inSim.sendMessage('Hello!'); // send IS_MSX
inSim.sendMessage('/spec Flame CZE'); // send IS_MST
inSim.sendMessageToConnection(4, 'Hello, UCID 4!'); // send IS_MTC
inSim.sendMessageToPlayer(6, 'Hello, PLID 4!'); // send IS_MTC

[Degats]

From experience, it's very useful to have abstractions like these for some specific packets, especially buttons as the Text field has some complex behaviour.

[theangryangel]

Something you may also want to have in the back of your head, at some point in insim.rs I had a send_and_wait_for_response style method where it would automatically set the reqi on a given packet (ensuring it was unique on a per-insim-connection basis), and then wait for a response where the reqi was the same, and then return the packet.

I dropped it, with the plan to bring it back (eventually) - but it is something I've needed at some point in most insim things I've worked on.

[mkapal]

@theangryangel Thanks, that's a good idea, I will consider it for the future.