...

Package field

import "github.com/Diarkis/diarkis/field"
Overview
Index

Overview ▾

Package field ▷

Field - Unified MMO

Allows the users to connect in the same world MMO-style without server separation. Extremely low-latency and scalable. Easy to maintain as it auto-scales.

[IMPORTANT]: There is a known edge case with position value calculation with negative values. If x and/or y are negative, it they will not be considered within the field of vision with positive values.

Configurations

Field configuratiuons are explained below.

{
  "fieldSize": 377970000,
  "fieldOfVisionSize": 100,
  "syncLimitOnDiscard": 50,
  "ttl": 10000
}

▶︎ Configuration Values

fieldSize - Default is 377970000

The surface area size of the entire world to be auto-devided across the server nodes.
fieldOfVisionSize - Default is 100

This is the size of field of vision. The field of vision does not change and remains the same for all clients.

syncLimitOnDiscard - Default is 50

Limit of how many other clients to sync on user discard (disappearance packet).

ttl - Default is 10000

TTL of the client position data in milliseconds.

Index ▾

func AddUserPositionValidation(validator func(*user.User, int64, int64, int64) bool)
func AfterDisappearCmd(callback func(*user.User, func(error)))
func AfterSyncCmd(callback func(*user.User, func(error)))
func AfterSyncInitCmd(callback func(*user.User, func(error)))
func BeforeDisappearCmd(callback func(*user.User, func(error)))
func BeforeSyncCmd(callback func(*user.User, func(error)))
func BeforeSyncInitCmd(callback func(*user.User, func(error)))
func Broadcast(userData *user.User, uList []*UserEntity, ver uint8, cmd uint16, msg []byte, reliable bool)
func CalcDistance(myX, myY, yourX, yourY int64) int64
func Disappear(userData *user.User, syncLimit int)
func DiscardNPCByID(id string) bool
func ExposeCommands()
func GetGridRangeByGridKey(gridKey string) (int64, int64, int64, int64)
func GetGridSize() int64
func GetGrids() []string
func GetServerSyncLimit() int
func GetUserPosition(userData *user.User) (int64, int64, int64)
func IsUserInSight(mySID, otherSID string) bool
func IsWS()
func PrintGridLayout(gl *GridLayout)
func Reconnect(meshEndPoint string, userData *user.User, callback func(error, string))
func ServerSync(x, y, z int64, message []byte, syncLimit int, reliable bool)
func SetCustomFilter(customFilterID uint8, filter func(*user.User, []*UserEntity) []*UserEntity)
func SetOnGridUpdated(callback func([]string))
func SetOnNPCTransported(callback func(*Npc))
func Setup(confpath string)
func Sync(userData *user.User, x, y, z int64, syncLimit int, msg []byte) (string, []*UserEntity, []*UserEntity, [][]byte)
func SyncBroadcast(userData *user.User, x, y, z int64, syncLimit int, ver uint8, cmd uint16, msg []byte, reliable bool)
func SyncNearbyGrids(userData *user.User, x, y, z int64, customFilterID uint8, syncLimit int, msg []byte, reliable bool, callback func(error, [][]byte))
func Update(userData *user.User, x int64, y int64, z int64) string
type GridData
    func GetMyGrids() []*GridData
    func (gd *GridData) GetKey() string
    func (gd *GridData) GetPosition() (int64, int64)
type GridLayout
    func NewGridLayout(gd *GridData, parent *GridLayout) *GridLayout
    func (gl *GridLayout) Add(gd *GridData)
type Npc
    func GetNPCByID(id string) *Npc
    func NewNPC(x int64, y int64, z int64) (*Npc, error)
    func (n *Npc) Get(key string) interface{}
    func (n *Npc) GetID() string
    func (n *Npc) GetPosition() (int64, int64, int64)
    func (n *Npc) Incr(key string, delta int) (int, error)
    func (n *Npc) Set(key string, value interface{})
    func (n *Npc) SetOnDiscard(cb func(*Npc))
    func (n *Npc) SetPosition(x int64, y int64, z int64)
type UserEntity
    func ApplyCustomFilter(customFilterID uint8, userData *user.User, uList []*UserEntity) []*UserEntity
    func FindUsersByPosition(x, y, z int64, howMany int) ([]*UserEntity, []string)
    func (ue *UserEntity) GetCoordinates() (int64, int64)
    func (ue *UserEntity) GetDistance() int64
    func (ue *UserEntity) GetID() string
    func (ue *UserEntity) GetSID() string

func AddUserPositionValidation

func AddUserPositionValidation(validator func(*user.User, int64, int64, int64) bool)

AddUserPositionValidation registers a validation function to be called on Sync

validator - Custom function to be invoked for position validation.

func AfterDisappearCmd

func AfterDisappearCmd(callback func(*user.User, func(error)))

AfterDisappearCmd registers a command to be executed after field disappear: Must be called before ExposeCommands()

func AfterSyncCmd

func AfterSyncCmd(callback func(*user.User, func(error)))

AfterSyncCmd registers a command to be executed after field sync: Must be called before ExposeCommands()

func AfterSyncInitCmd

func AfterSyncInitCmd(callback func(*user.User, func(error)))

AfterSyncInitCmd registers a command to be executed after field sync: Must be called before ExposeCommands()

func BeforeDisappearCmd

func BeforeDisappearCmd(callback func(*user.User, func(error)))

BeforeDisappearCmd registers a command to be executed before field disappear: Must be called before ExposeCommands()

func BeforeSyncCmd

func BeforeSyncCmd(callback func(*user.User, func(error)))

BeforeSyncCmd registers a command to be executed before field sync: Must be called before ExposeCommands()

func BeforeSyncInitCmd

func BeforeSyncInitCmd(callback func(*user.User, func(error)))

BeforeSyncInitCmd registers a command to be executed before field sync: Must be called before ExposeCommands()

func Broadcast

func Broadcast(userData *user.User, uList []*UserEntity, ver uint8, cmd uint16, msg []byte, reliable bool)

Broadcast broadcast a message to the list of users found by Sync or FindUsersByPosition function

userData - User that sends broadcast.
uList    - An array of user entities to send broadcast to.
ver      - Command version to be used as braodcast.
cmd      - Command ID to be used as broadcast.
msg      - Message byte array to be sent as broadcast.
reliable - If true, UDP will become RUDP.

func CalcDistance

func CalcDistance(myX, myY, yourX, yourY int64) int64

CalcDistance calculates distance using triangle

      ┬──────────>(Me)
      │          /|
      │         / |
      │        /  |
 distance     /   | Y
      │      /    |
      │     /    _|
      └───>/____|_|
       (You)  X

myX   - X coordinate to calculate the distance against yourX.
myY   - Y coordinate to calculate the distance against yourY.
yourX - X coordinate to calculate the distance against myX.
yourY - Y coordinate to calculage the distance against myY.

func Disappear

func Disappear(userData *user.User, syncLimit int)

Disappear removes the user client from field map

userData  - User that will be disappear.
syncLimit - Maximum number of remote users to synchronize the disappearance.

func DiscardNPCByID

func DiscardNPCByID(id string) bool

DiscardNPCByID deletes an NPC with matching ID

[NOTE] Uses mutex lock internally.

id - Target NPC ID to delete.

func ExposeCommands

func ExposeCommands()

ExposeCommands exposes commands to the client to work with Field package

func GetGridRangeByGridKey

func GetGridRangeByGridKey(gridKey string) (int64, int64, int64, int64)

GetGridRangeByGridKey returns grid range of x and y. This function works only with grids of the node.

[NOTE] Uses mutex lock internally.

return x1, x2, y1, y2

Grid key is obtained by GetGrids()

gridKey - Target grid key to retrive the grid positions.

func GetGridSize

func GetGridSize() int64

GetGridSize returns the size of the grid

func GetGrids

func GetGrids() []string

GetGrids returns a list of grids the node is assigned to

func GetServerSyncLimit

func GetServerSyncLimit() int

GetServerSyncLimit returns serverSyncLimit

func GetUserPosition

func GetUserPosition(userData *user.User) (int64, int64, int64)

GetUserPosition returns the current user position: x, y, z

[NOTE] Uses mutex lock internally.

userData - Target user to retrieve the positions of.

func IsUserInSight

func IsUserInSight(mySID, otherSID string) bool

IsUserInSight evalutes if the remote user is in sight or not

[NOTE] Uses mutex lock internally.

mySID    - Target SID of the user to check if the other user is in sight or not.
otherSID - Target SID of the other user to check if my user is in sight or not.

func IsWS

func IsWS()

IsWS called internally by commands.go

func PrintGridLayout

func PrintGridLayout(gl *GridLayout)

PrintGridLayout prints the grid layout into standard out

func Reconnect

func Reconnect(meshEndPoint string, userData *user.User, callback func(error, string))

Reconnect returns the end point of the node for the client to reconnect to

[NOTE] Uses mutex lock internally.

meshEndPoint - Internal server address to direct the user for reconnection.
userData     - Target user to direct the reconnection.
callback     - Callback to be invoked when server operation of reconnection is completed.

func ServerSync

func ServerSync(x, y, z int64, message []byte, syncLimit int, reliable bool)

ServerSync sends messages from the server to the clients within the view

[NOTE] Uses mutex lock internally.

This is meant to be used to synchronize NPC entities from the server to the client.

x         - X coordinate to be used to synchronize.
y         - Y coordinate to be used to synchronize.
z         - Z space to be used to synchronize.
syncLimit - Maximum number of users to synchronize with.
reliable  - If true, UDP will become RUDP.

[NOTE] Z space is not a coordinate, but it describes dimension or space. For example, users with the same x and y with different z will not "see" each other.

func SetCustomFilter

func SetCustomFilter(customFilterID uint8, filter func(*user.User, []*UserEntity) []*UserEntity)

SetCustomFilter defines a custom filter that will be invoked when user client indicates while synchronizing. The purpose of the filter is to manipulate the users in sight for synchronizing.

customFilterID - Unique ID to identify the cuntom filter.
filter         - Custom operation function to perform filterting.

func SetOnGridUpdated

func SetOnGridUpdated(callback func([]string))

SetOnGridUpdated registers a callback function on grid map updated.

[NOTE] Uses mutex lock internally.

The callback receives grid x1, y1 and grid x2, y2.

Each node has two sets of grid x and y

callback - Callback to be invoked when grids are updated.

func SetOnNPCTransported

func SetOnNPCTransported(callback func(*Npc))

SetOnNPCTransported registers a callback on NPC transport

callback - Callback to be invoked when the target NPC is transported to another server based on X and Y.

func Setup

func Setup(confpath string)

Setup setup Field module

confpath - Absolute path of the configuration file to be loaded.

func Sync

func Sync(userData *user.User, x, y, z int64, syncLimit int, msg []byte) (string, []*UserEntity, []*UserEntity, [][]byte)

Sync updates its own position and find others within the sight (fieldOfVisionSize) - z is used as a literal value instead of range like x and y. Use z value to create "different" area.

[NOTE] Uses mutex lock internally.

// returned values:
meshNodeEndPoint, usersInSight, usersNotInSight, userMessageListInsight := field.Sync(userData, x, y, z, syncLimit, message)

userData  - User that will be synchronize the data.
x         - X position of the user to synchronize.
y         - Y position of the user to synchronize.
z         - Z space of the user to synchronize.
syncLimit - Maximum number of users to synchronize with.
msg       - Synchronize byte array data.

[NOTE] Z space is not a coordinate, but it describes dimension or space. For example, users with the same x and y with different z will not "see" each other.

func SyncBroadcast

func SyncBroadcast(
    userData *user.User,
    x, y, z int64,
    syncLimit int,
    ver uint8, cmd uint16,
    msg []byte,
    reliable bool,
)

SyncBroadcast sends a message to clients that are in sight with ver and cmd given

[NOTE] Uses mutex lock internally.

userData *user.User - User to send synchronize broadcast.

x        - X coordinate to be used to synchronize.
y        - Y coordinate to be used to synchronize.
z        - Z space to be used to synchronize.
ver      - Command version to be used to be sent as broadcast.
cmd      - Command ID to be used to be sent as broadcast.
msg      - Synchronize byte array data.
reliable - If true, UDP will become RUDP.

[NOTE] Z space is not a coordinate, but it describes dimension or space. For example, users with the same x and y with different z will not "see" each other.

func SyncNearbyGrids

func SyncNearbyGrids(
    userData *user.User,
    x, y, z int64,
    customFilterID uint8,
    syncLimit int,
    msg []byte,
    reliable bool,
    callback func(error, [][]byte),
)

SyncNearbyGrids synchronize with nearby remote grids including remote grids

[NOTE] Uses mutex lock internally.

userDat  - User to synchronize.
x        - X position of the user to synchronize.
y        - Y position of the user to synchronize.
z        - Z space of the user to synchronize.
msg      - Synchronize byte array data.
reliable - If true, UDP will become RUDP.
callback - Callback to be invoked when the oeration is completed.

[NOTE] Z space is not a coordinate, but it describes dimension or space. For example, users with the same x and y with different z will not "see" each other.

func Update

func Update(userData *user.User, x int64, y int64, z int64) string

Update updates the given userData(client)'s position data and returns a mesh address, if the client must reconnect to a new mesh node.

[NOTE] Uses mutex lock internally.

userData - Target user to update its X, Y, and Z.
x        - X coordinate to replace the current value with.
y        - Y coordinate to replace the current value with.
z        - Z space to replace the current value with.

[NOTE] Z space is not a coordinate, but it describes dimension or space. For example, users with the same x and y with different z will not "see" each other.

type GridData

GridData grid data with size and coordinate

type GridData struct {
    // contains filtered or unexported fields
}

func GetMyGrids

func GetMyGrids() []*GridData

GetMyGrids returns an array of grids of the node

[NOTE] Uses mutex lock internally.

func (*GridData) GetKey

func (gd *GridData) GetKey() string

GetKey returns the unique key of the grid

func (*GridData) GetPosition

func (gd *GridData) GetPosition() (int64, int64)

GetPosition returns X and Y coordinate of the grid

x, y := gd.GetPosition()

type GridLayout

GridLayout is a representation of the layout of grids

type GridLayout struct {
    N      *GridLayout
    E      *GridLayout
    S      *GridLayout
    W      *GridLayout
    Parent *GridLayout
    Root   *GridData
}

func NewGridLayout

func NewGridLayout(gd *GridData, parent *GridLayout) *GridLayout

NewGridLayout creates a new GridLayout

func (*GridLayout) Add

func (gl *GridLayout) Add(gd *GridData)

Add adds a GridData to GridLayout

type Npc

Npc is a server-controlled non-playable-character data struct.

Npc should be synchronized with clients via ServerSync and should NEVER be controlled by clients

type Npc struct {
    sync.RWMutex
    // contains filtered or unexported fields
}

func GetNPCByID

func GetNPCByID(id string) *Npc

GetNPCByID returns an NPC with matching ID

[NOTE] Uses mutex lock internally.

id - Target NPC ID.

func NewNPC

func NewNPC(x int64, y int64, z int64) (*Npc, error)

NewNPC creates a new non-player-character entity to be controlled on the server and synchronized by ServerSync.

[NOTE] Uses mutex lock internally.

x - initial X coordinate of the new NPC to be created.
y - initial Y coordinate of the new NPC to be created.
z - initial Z space of the new NPC to be created.

[NOTE] Z space is not a coordinate, but it describes dimension or space. For example, users with the same x and y with different z will not "see" each other.

func (*Npc) Get

func (n *Npc) Get(key string) interface{}

Get returns custom property value

[NOTE] Uses mutex lock internally.

func (*Npc) GetID

func (n *Npc) GetID() string

GetID returns the unique ID of NPC

func (*Npc) GetPosition

func (n *Npc) GetPosition() (int64, int64, int64)

GetPosition returns X, Y position and Z space

func (*Npc) Incr

func (n *Npc) Incr(key string, delta int) (int, error)

Incr increments custom property (it must be an int) by delta

[NOTE] Uses mutex lock internally.

key   - Property name of the NPC to increment.
delta - Property value of the NPC to increment.

func (*Npc) Set

func (n *Npc) Set(key string, value interface{})

Set sets custom property

[NOTE] Uses mutex lock internally.

key   - Property name of the NPC to set.
value - Property value of the NPC to set.

func (*Npc) SetOnDiscard

func (n *Npc) SetOnDiscard(cb func(*Npc))

SetOnDiscard registers a callback function to be invoked on DiscardNPCByID

[NOTE] Uses mutex lock internally.

cb - Callback assigned to be invoked when the target NPC is deleted.

func (*Npc) SetPosition

func (n *Npc) SetPosition(x int64, y int64, z int64)

SetPosition sets X, Y position and Z space

x - X coordinate to assgin to the target NPC.
y - Y coordinate to assgin to the target NPC.
z - Z space to assign to the target NPC.

[NOTE] Z is not coordinate, but it describes dimension or space. For example, NPCs with same x and y with different z will not "see" each other.

type UserEntity

UserEntity a user data structure

type UserEntity struct {
    // contains filtered or unexported fields
}

func ApplyCustomFilter

func ApplyCustomFilter(customFilterID uint8, userData *user.User, uList []*UserEntity) []*UserEntity

ApplyCustomFilter executes pre-defined custom filter on the list of UserEntity to controll who to broadcast to

customFilterID - Unique ID to identify the cuntom filter.
userData       - User to apply the filter.
uList          - An array of user entities that are in sight to be manipulated.

func FindUsersByPosition

func FindUsersByPosition(x, y, z int64, howMany int) ([]*UserEntity, []string)

FindUsersByPosition returns an array of user entities and an array of user IDs within the given area (x, y, z)

[NOTE] Uses mutex lock internally.

x       - X coordinate to find the users with.
y       - Y coordinate to find the users with.
z       - Z space to find the users with.
howmany - Maximum number of users to find.

[NOTE] Z space is not a coordinate, but it describes dimension or space. For example, users with the same x and y with different z will not "see" each other.

func (*UserEntity) GetCoordinates

func (ue *UserEntity) GetCoordinates() (int64, int64)

GetCoordinates returns the X,Y position of UserEntity

func (*UserEntity) GetDistance

func (ue *UserEntity) GetDistance() int64

GetDistance returns the distance between the user and you

func (*UserEntity) GetID

func (ue *UserEntity) GetID() string

GetID returnns the user ID of the user

func (*UserEntity) GetSID

func (ue *UserEntity) GetSID() string

GetSID returns SID of the user