Ports & Devices

Devices are inventory items that go into a laptop's ports. Built in are the data stick and the boot sticks (USB-A), the power bank (USB-C), and the HDMI cable for casting. Other resources add their own devices, see Adding Device Types.

#Ports

A laptop has two USB-C ports, an HDMI port, and a status light on the left, and a USB-A port and an audio jack on the right.

A desktop computer has its ports in one row behind its screen, so its port view has a single page. It has no USB-C port, so no power bank goes in.

#Port View

At a placed laptop, choose Ports. The camera turns to one side of the laptop and a bar at the bottom lists that side's ports: each port's number, and the device in it or Empty.

• Pick a port with its number key or a click.
• An empty port lists the items you carry that fit it. The device under the cursor shows see-through in the port. Pick one to plug it in.
• A filled port offers Unplug.
• The device or port in focus is outlined.

The view closes once the laptop is picked up or you walk out of reach. Ports cannot be used while the laptop is being serviced.

A held laptop has no port view, as plugging something in takes both hands. Devices already in its ports stay in and show on it.

#Who May Plug In

With ports.others = true, the default, anyone at a placed laptop can plug devices in and pull them out, as with a real laptop. With false, only the character who put it down can.

CanPlugLaptopDevice and CanUnplugLaptopDevice in server/unlocked/hooks.lua limit it further, for example to owners only. See Can-Check Hooks.

#How Devices Are Kept

A plugged device is the exact item from the player's inventory slot, with its metadata. It moves into the laptop item's metadata under ports, so it stays in the laptop while it is put away and goes wherever the laptop item goes. Unplugging gives that same item back with the same metadata.

lua
metadata = {
    serial = "ZL-7K2M-9QX4",
    ports = {
        usba = {name = "usb_drive", metadata = {serial = "ZU-4HQ8-N2PW"}},
        usbc1 = {name = "laptop_powerbank", metadata = {serial = "PB-7F3K-92QD", charge = 0.64, durability = 64, description = "72 Wh, 20000 mAh · Charge 64%"}},
    },
}

With item = false, the server's KVP keeps the devices by the laptop's serial.

An item only leaves one side once the other side holds it. A player with no room for an unplugged device keeps it in the port, and two players pulling the same port never duplicate it. Every nearby player sees the devices on held and placed laptops.

#Data Sticks

ports.dataStick is the data stick, usb_drive by default, a plain flash drive with a blank strip of tape. Set it to false for none.

• It gets a serial in its metadata the first time it is plugged in.
• Its files are kept on the server by that serial, in the zyke_laptop_sticks table the resource creates on start. A stick handed to another player shows the same files in their laptop.
• maxBytes is what its files may take, 128 KiB by default, checked on the server. Keep it under 327680, as every save sends all the files.
• capacity is the size players see, 8 GB by default. The free space shown is scaled to it.

In every OS a plugged data stick shows as a removable drive in the Files app, for example USB Drive (E:) on Facade. Players copy, rename, and delete files on it, rename the stick, and eject it before pulling it out. Ejecting only makes it safe to pull out; the stick stays in the port until someone unplugs it. See Operating Systems.

#Boot Sticks in the Port

The boot menu offers the boot sticks plugged into the laptop's USB-A port as well as the ones the player carries, so a stick left in a laptop boots it for anyone at the keyboard. os.carriedSticks = false makes players plug the stick in first.

A stick the player only carries still shows in the USB-A port while the OS runs from it, unless another device is plugged in there. See Operating Systems.

#Power Bank

ports.powerBank is the power bank, laptop_powerbank by default, sold at the shop with the accessories. Plug it into either USB-C port from the port view of a placed laptop. Set powerBank = false for none.

The bank lies beside the laptop with a USB-C cable to the port, or on the floor below when the laptop stands at an edge. Its four lights show its charge, one per quarter, and are only lit while it charges or is filled.

• A held laptop without a battery runs on the bank alone.
• When the bank runs flat, the laptop runs on its battery again, or turns off without one. The player is told either way.
• With two banks, the first port with charge powers the laptop, then the next. On a placed laptop both fill.

Every OS shows where the power comes from and the bank's charge in its battery menu, and the port view shows the charge of a plugged bank.

#Settings

#Metadata

A bank given any other way, such as by an admin, gets these the first time the holder's inventory changes. A bank keeps its serial and charge while it is plugged in, so pulling it out gives it back with the charge it has.

#Without a Battery Need

With hardware.needsBattery = false, a held laptop runs as if plugged in. Its battery never drains, and a power bank in it neither fills nor drains. Nothing needs the bank then, so take laptop_powerbank out of the shop's accessories in shared/unlocked/shop.lua as well. See Hardware & Servicing.

#Adding Device Types

Other resources register their own devices from a server script with RegisterDeviceType: the items, the port kinds they fit, the prop shown in the port, and optionally storage that makes the device a drive the OS mounts, like the data stick. The type belongs to the registering resource and is removed when it stops; devices already in a port stay there and can still be pulled out. An item can only be one device type.

The server exports GetLaptopDevices, GetSessionDevices, PlugDevice, and UnplugDevice, and the events zyke_laptop:DevicePlugged and zyke_laptop:DeviceUnplugged, let a resource read and change what is in the ports. PlugDevice and UnplugDevice run the same checks and hooks as the port view. Pages see the plugged devices through the JavaScript SDK.

See Register Device Type for the full example.