README.en-us.md

#Luban

---

links

• README - English
• github link
• gitee link

---

introduce

luban is your best game configuration solution.

Luban efficiently handles data such as excel, json, and xml that are common in game development, checks for data errors, generates code in various languages ​​such as c#, and exports it to various formats such as bytes or json.

Luban unifies the game configuration development workflow, greatly improving the efficiency of planning and programming.

Core Features

• Powerful data parsing and conversion capabilities {excel(csv,xls,xlsx), json, bson, xml, yaml, lua, unity ScriptableObject} => {binary, json, bson, xml, lua, yaml, erlang, custom format }
• Enhanced excel format that can be easily configured like simple lists, substructures, structured lists, and arbitrarily complex deeply nested structures.
• Complete type system, support OOP type inheritance, with data in excel, json, lua, xml and other formats flexibly and elegantly to express complex GamePlay data such as behavior trees, skills, plots, and copies
• Support to generate c#, java, go, c++, lua, python, javascript, typescript, erlang, rust code
• Support generating protobuf(schema + binary + json), flatbuffers(schema + json), msgpack(binary)
• Powerful data verification capabilities. ref reference check, path resource path, range range check, etc.
• Perfect localization support. Static text value localization, dynamic text value localization, time localization, main-patch multi-region version
• Powerful and flexible customization capabilities, support for custom code templates and data templates
• Generic generation and caching tool. Can also be used to generate code like protocols, databases, or even as an object caching service
• Good support for mainstream engines, all platforms, mainstream hot update solutions, mainstream front-end and back-end frameworks. Support mainstream engines such as unity, unreal, cocos2x, and WeChat mini-games. The tool itself is cross-platform and can work well on Win, Linux, and Mac platforms. [See details](https://focus-creative-games.github.io/lubandoc/feature.html#%E6%94%AF%E6%8C%81%E4%B8%BB%E6%B5%81% E7%9A%84%E6%B8%B8%E6%88%8F%E5%BC%80%E5%8F%91%E8%AF%AD%E8%A8%80)

See feature for full features

Documentation

• Quick Start

• Document, it is relatively complete, if you have any questions, please check this document first.

• Example Project (github) (gitee )

• Version Changelog

• Support and Contact

  • QQ group: 692890842 (Luban development exchange group). If you have any questions about use, please add the QQ group to ask in time, and someone will help you at any time.
  • Email: taojingjian#gmail.com

Excel format overview

For a complete example, please refer to Excel Format Introduction

Normal table

##var	id	x1	x5	x6	s1	s2	v3	t1
##type	int	bool	long	float	string	text#sep=|	vector3	datetime
##	id	desc1	desc2	desc3	desc4	desc7	desc1	time
	1	false	1000	1.2	hello	key1|world1	1,2,3	1999-10-10 11:12:13
	2	true	1000	2.4	world	key2|world2	2,4,5	1999-10-12 11:12:13

Raw data list

##var	id	arr1	arr2				arr3	arr4
##type	int	(array#sep=;),int	list,int				(list#sep=|),string	list,string
##	id	desc1	desc2				desc3	desc4
	1	1;2;3	1	2			xx|yy	xxx	zzz
	2	2;4	3	4	5		aaaa|bbbb|cccc	aaa	bbb	ccc
	3	2;4;6	3	4	5	6	aaaa|bbbb|cccc	aaa	bbb	ccc

substructure

Reward is a substructure containing the three fields of "int item_id; int count; string desc;".

##var	id	reward			reward2			reward3
##type	int	Reward			Reward			Reward#sep=,
##var		item_id	count	desc
	1	1001	10	item 1	1002< /td>	11	item 2	1002,1,item 3
	2	2001	10	item 2	2002< /td>	20	item 4	2003,2,item 5

Structure List 1

##var	id	rewards1						rewards2
##type	int	list,Reward						list,Reward#sep=,
##	id	reward list desc1						reward list desc2
	1	1001	1	desc1	1002	2	desc2	1001,1,desc1	1002,2,desc2	1003,3,desc3
	2	1001	1	desc1				1001,1,desc1	1002,2,desc2

Structure List 2

##var	id	name	rewards
##type	int	string	list,Reward
##var			0			1			2
	1	task1	1001	10	desc1	1002	12	desc2	1003	13	desc3
	2	task1	1003	30	desc3	1004	40	desc4
	3	task1	1005	50	desc5

Structure List 3

##var	id	name	rewards
##type	int	string	list,Reward
##var			0			1			2
##var			item_id	num	desc	item_id	num	desc	item_id	num	desc
	1	task1	1001	10	desc1	1002	12	desc2	1003	13	desc3
	2	task1	1003	30	desc3	1004	40	desc4
	3	task1	1005	50	desc5

Multi-row table

##var	id	name	*stages
##type	int	string	list,Stage
##var			id	name	desc	location	item_id	num
##	id	desc1	desc1	desc2	desc3	desc4	desc5	desc6
	1	task1	1	stage1	stage desc1	1,2,3	1001	1
			2	stage2	stage desc2	1,2,3	1001	1
			3	stage3	stage desc3	1,2,3	1002	1
	2	task2	1	stage1	stage desc1	1,2,3	1001	1
			2	stage2	stage desc2	1,2,3	1002	1

Multi-level subheadings of type map

##var	id	lans
##type	int	map,string,string
##var		ch-zn	en	jp	fr
	1	apple	apple	aaa	aaa
	2	banana	banana	bbb	bbb

Type inheritance (suitable for skills, buff related configuration)

##var	id	shape				shape2
##type	int	Shape				Shape
##var		$type	radius	width	height
	1	Circle	10			Circle	100
	2	Rectangle		10	20	Rectangle	10	20
	3	Circle	10			Triangle	15	15	15
	4	Circle	10			Rectangle	30	20

Multiple primary key table (joint index)

Multiple keys form a joint unique primary key.

##var	key1	key2	key3	num
##type	int	long	string	int
	1	1	aaa	123
	1	1	bbb	124
	1	2	aaa	134
	2	1	aaa	124
	5	6	xxx	898

Multiple primary key table (independent index)

Multiple keys are indexed independently.

##var	key1	key2	key3	num
##type	int	long	string	int
	1	2	aaa	123
	2	4	bbb	124
	3	6	ccc	134
	4	8	ddd	124
	5	10	eee	898

Singleton table

Some configurations only have one copy globally, such as the opening level of the guild module, the initial size of the backpack, and the upper limit of the backpack. In this case, it is more appropriate to use a singleton table to configure these data.

##var	guild_open_level	bag_init_capacity	bag_max_capacity	newbie_tasks
##type	int	int	int	list,int
##	desc1	desc2	desc3	desc4
	10	100	500	10001, 10002

Vertical table

##var#column	##type	##
guild_open_level	int	desc1	10
bag_init_capacity	int	desc2	100
bag_max_capacity	int	desc3	500
newbie_tasks	list,int	desc4	10001,10002

json, lua, xml, yaml format quick overview

Take the behavior tree as an example to show how to configure the behavior tree configuration in json format. For formats such as xml, lua, yaml, etc., please refer to detailed documentation.

{
  "id": 10002,
  "name": "random move",
  "desc": "demo behaviour tree",
  "executor": "SERVER",
  "blackboard_id": "demo",
  "root": {
    "$type": "Sequence",
    "id": 1,
    "node_name": "test",
    "desc": "root",
    "services": [],
    "decorators": [
      {
        "$type": "UeLoop",
        "id": 3,
        "node_name": "",
        "flow_abort_mode": "SELF",
        "num_loops": 0,
        "infinite_loop": true,
        "infinite_loop_timeout_time": -1
      }
    ],
    "children": [
      {
        "$type": "UeWait",
        "id": 30,
        "node_name": "",
        "ignore_restart_self": false,
        "wait_time": 1,
        "random_deviation": 0.5,
        "services": [],
        "decorators": []
      },
      {
        "$type": "MoveToRandomLocation",
        "id": 75,
        "node_name": "",
        "ignore_restart_self": false,
        "origin_position_key": "x5",
        "radius": 30,
        "services": [],
        "decorators": []
      }
    ]
  }
}

Code usage preview

Here we only briefly show the usage of c#, typescript, and go languages ​​in development. For more languages ​​and more detailed usage examples and codes, see Example Project.

• C# usage example

// One line of code can load all configuration. cfg.Tables contains one instance field for all tables.
var tables = new cfg.Tables(file => return new ByteBuf(File.ReadAllBytes(gameConfDir + "/" + file + ".bytes")));
// access a singleton table
Console.WriteLine(tables.TbGlobal.Name);
// access the normal key-value table
Console.WriteLine(tables.TbItem.Get(12).Name);
// support operator [] usage
Console.WriteLine(tables.TbMail[1001].Desc);

• Typescript usage example

// One line of code can load all configuration. cfg.Tables contains one instance field for all tables.
let tables = new cfg.Tables(f => JsHelpers.LoadFromFile(gameConfDir, f))
// access a singleton table
console.log(tables.TbGlobal.name)
// access the normal key-value table
console.log(tables.TbItem.get(12).Name)

• go example

// One line of code can load all configuration. cfg.Tables contains one instance field for all tables.
if tables , err := cfg.NewTables(loader) ; err != nil {
 println(err.Error())
 return
}
// access a singleton table
println(tables.TbGlobal.Name)
// access the normal key-value table
println(tables.TbItem.Get(12).Name)

route map

• Added unity built-in editor
• Added unreal built-in editor
• Supplemental unit tests

License

Luban is licensed under the MIT license.