EasyBullet

A simple bullet runtime that handles network replication, network syncing, and adjusts the rendered bullets by client framerate.

Getting Started

Download the EasyBullet.rbxmx file and drag it into studio

Or grab the Marketplace model and insert it via the Toolbox window

Use NPM to install EasyBullet into your Roblox-TS project:

npm install @rbxts/easybullet

To build EasyBullet into a model, use:

rojo build -o "EasyBullet.rbxmx" build.project.json

To serve EasyBullet into your game, use:

rojo serve

To install using wally, add to your wally.toml dependencies:

EasyBullet = "zachcurtis/[email protected]"

Then run:

wally install

Example

local EasyBullet = require(path.To.EasyBullet)

local defaultSettings = {
    Gravity = true,
    RenderBullet = true,
    BulletColor = Color3.new(0.945098, 0.490196, 0.062745),
    BulletThickness = .1,
    FilterList = {},
    FilterType = Enum.RaycastFilterType.Exclude,
    BulletPartProps = {},
    BulletData = {}
}

local easyBullet = easyBullet.new(defaultSettings)

easeBullet:FireBullet(barrelPosition, bulletVelocity)

easyBullet.BulletHitHumanoid:Connect(function(shootingPlayer, rayResult, hitHumanoid)
    hitHumanoid:TakeDamage(15)
end)

API

EasyBulletSettings

export type EasyBulletSettings = {
    Gravity: boolean?, -- Should the bullet curve according to workspace.Gravity
    RenderBullet: boolean?, -- Should EasyBullet display a rendered bullet on the client
    BulletColor: Color3?, -- Sets the color of the bullets rendered
    BulletThickness: number?, -- Sets the thickness of the bullets in studs
    FilterList: {[number]: Instance}?, -- An array of instances assigned to RayParams.FilterDescendantsInstances
    FilterType: Enum.RaycastFilterType?, -- The RaycastFilterType, either Include or Exclude
    BulletPartProps: {[string]: unknown}?, -- A dictionary of properties matching the properties of BasePart to override the bullet part rendering. Cannot include keys "CFrame", "Size", or "Color"
    BulletData: {[string]: unknown}? -- A dictionary of any data you wish to associate with this bullet. HitVelocity and BulletId are reserved keys for this table, and are set by EasyBullet before passing the BulletData table to the BulletHit, BulletHitHumanoid, and BulletUpdated events. Useful for variations such as displaying a different hit effect for a sniper, or altering the damage dependent on the gun type.
}

Default EasyBulletSettings

| Field | Type | Default | | ------- | ------- | ------- | | Gravity | boolean | true | | RenderBullet | boolean | true | | BulletColor | Color3 | Color3.new(0.945098, 0.490196, 0.062745) | | BulletThickness | number | .1 | | FilterList | { [number]: Instance } | {} | | FilterType | RaycastFilterType | Enum.RaycastFilterType.Exclude | | BulletPartProps | { [string]: unknown } | {} | | BulletData | { [string]: unknown } | {} |

Methods

Constructor - EasyBullet is a singleton so it will only be constructed once per server or client, but any subsequent calls to EasyBullet.new will return the constructed singleton. Only the settings overrides passed to the first constructor will be used.

local EasyBulletSettingsOverrides = {
    BulletColor = Color3.new(1, 0, 0),
    Gravity = false
}

local easyBullet = EasyBullet.new(EasyBulletSettingsOverrides)

FireBullet - call on client to fire a bullet for a player, or on the server to fire a bullet for a NPC

local direction = mouse.Hit.Position - gun.BarrelPosition
local velocity = direction.Unit * 400

local optionalEasyBulletSettings = {
    BulletThickness = .4
}

easyBullet:FireBullet(gun.BarrelPosition, velocity, optionalEasyBulletSettings)

BindCustomCast - pass a callback that returns a RaycastResult or nil to implement custom raycast behavior, such as lag compensation for network delayed character positions

easyBullet:BindCustomCast(function(shooter: Player?, lastFramePosition: Vector3, thisFramePosition: Vector3, elapsedTime: number, bulletData: {[string]: Unknown})
    local direction = lastFramePosition - thisFramePosition

    local raycastParams = RaycastParams.new()

    -- npc shots have no shooting player
    if shooter then
        raycastParams.FilterDescendantsInstances = {shooter.Character}
        raycastParams.FilterType = Enum.RaycastFilterType.Exclude
    end

    return workspace:Raycast(lastFramePosition, direction, raycastParams)
end)

BindShouldFire - pass a callback that returns a boolean to provide a means of filtering bullets before they're fired. The bullet will initially be networked before the ShouldFire callback is called, but the bullet will automatically clean it's self up across the network if the ShouldFire callback returns false.

easyBullet:BindShouldFire(function(shooter: Player?, barrelPosition: Vector3, velocity: Vector3, ping: number, easyBulletSettings: Bullet.EasyBulletSettings?)
    if not shooter or not shooter.Character or not shooter.Character.HumanoidRootPart then
        return false
    end

    local humanoid = shooter.Character.Humanoid
    local rootPart = shooter.Character.HumanoidRootPart

    local discrepancy = (barrelPosition - rootPart.Position).Magnitude
    local desyncTolerance = (shooter:GetNetworkPing() * humanoid.WalkSpeed) * 1.2

    -- return true if barrelPosition is within how far the player could have walked in that time
    return discrepancy <= desyncTolerance
end)

Events

BulletHit - fired whenever a bullet hits something

easyBullet.BulletHit:Connect(function(shootingPlayer: Player?, raycastResult: RaycastResult, bulletData: {[string]: Unknown} | {HitVelocity: Vector3})
    print(raycastResult.Instance.Name)
end)

BulletHitHumanoid - fired whenever a bullet hits a part belonging to a model with a child humanoid

easyBullet.BulletHitHumanoid:Connect(function(shootingPlayer: Player?, raycastResult: RaycastResult, hitHumanoid: Humanoid, bulletData: {[string]: Unknown} | {HitVelocity: Vector3})
    hitHumanoid:TakeDamage(15)
end)

BulletUpdated - fired every time the bullet updates. Useful for rendering custom bullets.

easyBullet.BulletUpdated:Connect(function(lastFramePosition: Vector3, thisFramePosition: Vector3, bulletData: {[string]: unknown})
    local direction = lastFramePosition - thisFramePosition

    bulletPart.Size = Vector3.new(.2, .2, direction.Magnitude)
    bulletPart.CFrame = CFrame.lookAt(lastFramePosition, thisFramePosition) * CFrame.new(0,0, -direction.Magnitude * .5)
end)