longBit en

longBit

• Versão: 3.5.3
• Description:

  This curious book was designed and created with the intention of abstract the manipulation of persistent memory of the Tic80 and extend artificially its store capacity, through of the division of its space in Sub-Memories.

"Sub-Memories"

  The division process, carried out by functions of this book, become possible store until nine numberic characteres in each of the 256 persistent memories of the Tic80. These spaces are named of sub-memories (in the contexto of this book), so:

• 14 fill two sub-memories.
• 60870 fill five sub-memories.
• 1194261537 exceed the limit (x10 > x9), for this cannot to be stored.

Note

The highest value that can be stored in "integer" spaces is 4.294.967.295, already in sub-memóries is 999.999.999.

  Some functions require the specification of the sub-memory index (1-9), in this cases is important remeber like the sub-memories are organized.

  For become the explication more easy, consider this example:

Type	Value
Index	1
Class	"player_xy"
Value	104070888

  This space is filled by two values, respectivally, the positions x and y, beyond it has three empty spaces, propositally, filled by number 8. Then:

• For access X is necessary use the index 1.
• For access Y is necessary use the index 4.

Important

There is not necessity of request of individually manner the values reponsables by composer a number more great that nine, already that there is possibility of specifies the width of the values in all functions that require a sub-memory index.

Classes

  This is the name given to the "nickname" assigned to the memory spaces (specified). Defined through of the function lbit.setClass().

  This is a way to replace the numeric indexes for keywords, so easily the legibility of the code and the distinction of different memory spaces.

  By example, instead of use 1 for refer to the reserved spaces for configurations, it can use "configurations", "conf" or any other string.

Topics

• Boot and cleanup
  • boot
  • clear
  • setClass
• Update
  • setAll
  • setNum
  • swapClass
  • update
• Get values
  • getAll
  • getBool
  • getClass
  • getNum

Functions

boot

• Description: store the values specified in a sequence of memories, but only case this memory is empty or case the (re)atribuition is forced.
• Return: a boolean values that indicate if all the values forneced were stored in persistent memory.

Structure

• boot(values, [force=false], [init=0], [left=false], [empty=0])
  • values (string matrix): values that will be add to the memories.
  • force (boolean): specifies that valid values already stored must be replaced.
  • init (number): the index of the first sub-memory that will receive a value.
  • left (boolean): specifies if empty sub-memories must be filled from left to right (---123).
  • empty (number): value that will be used to fill the (possible) empty spaces that stay in sub-memory(ies)

Tip

Use the header -- saveid: any_name in your catridge, for that the values stored in persistent memory of the Tic80 will not be losed after changes in the project code; use boot inside of the function BOOT, native from Tic80 API.

Example

function BOOT()
	
	local values = {
		"101020",    -- configirations
		"120068100", -- player: x, y, hp
		"0"          -- achievements
	}
	
	lbit.boot(values, nil, nil, 8)
	
	-- [...]

---

Come back to top

---

clear

• Description: discarts the informations stored in the memories and/or discarts the classes that were defined.
• Return: a boolean value, that indicate if some change was realized, and a numeric value, that indicate who many memories and/or classes were cleaned.

Structure

• clear(type, [absolute=false], [init=0], [max = 255])
  • type (string): tag specifying what must be clean ("all", "memory", "class", "noClass", "noMemory").
  • absolute (boolean): specifies if the sub-memories structure must be destroyed. Not generate none effect case type is equal to the "class" or to the "noMemory".
  • init (number): first index that will be clean.
  • max (number): last index that will be clean.

Warning

The classes are held only during the runtime, so, if clean("noClass", nil, 0, 255) will be called before the class will be defined, all memories will be clean.

Note

"noClass" clear values present in memories without defined classes. Already "noMemory" clear classes that does not have a (valid) defined memory.

Example

local function restartMEM(keyID, clickOn)
	if keyp(keyID) or (clickOn and table.pack(mouse())[3]) then
		lbit.clear("memory")
	end
end

---

Come back to top

---

setClass

• Description: define a serie of memory classes.
• Return: a boolean values that indicate if all classes provided were defined.

Structure

• setClass(classes, [force=false], [init=0])
  • classes (string matrix): classes that will be define.
  • force (boolean): specifies that classes already defined must be replace.
  • init (number): index of the first memory that will receive a class.

Example

function BOOT()
	-- start memory and its classes
	local values, classes
	
	values = {
		"0", "0", -- it will filled with zeros
		"104106", -- music, music volume (x2), sound, sound volume (x2)
		"064104", -- player: x, y
	}
	
	classes = {"score", "skins", "sounds", "player"}
	
	lbit.boot(values)
	lbit.setClass(classes)

	-- [...]

---

Come back to top

---

setAll

• Description: record a value in a memory, disregard sub-memories already defined it.
• Return: 0 case the operation is a success and protect == false.

Structure

• setAll(value, class, [update=false], [protect=false])
  • value (string ou number): values that will be assign (or added orsubtracted) in the memory.
  • class (string): memory class.
  • update (boolean): specifies if the values must be updated instead of recorded.
  • protect (boolean): specifies that, in case of underflow or overflow, instead of a fatal error will be generated, the function, respectively, will return -1 and it will record the minimum value to each sub-memories or it will return 1 and it will record the maximum values to each sub-memory.

Note

The error underflow only can occur case the memory in question don't have yet been defined and a values minor that 100.000.000 will be specified for it.

Tip

lbit.setAll("1583", "example") replaca the currect values of the sub-memory, of "example", by 1583, already lbit.setAll("6", "example"), add 6 to the current values.

Example

local function updateScore(values)
	-- debug
	if #values ~= 5 then
		trace("Invalid quantity of indexes", 3)
		exit()
	end
	
	-- players
	local classes = {"red", "blue", "yellow", "green", "purple"}
	
	-- add values to memory
	for i = 1, #classes do
		lbit.setAll(values[i], classes[i], true)
	end

end

---

Come back to top

---

setNum

• Description: (re-)record a values in one or more sub-memories.
• Return: none.

Structure

• setNum(value, id, class, [length=1])
  • value (number): value that will be (re-)recorded in the sub-memory.
  • id (number): index of the sub-memory (1-9).
  • class (string): memory class.
  • length (number): quantity of numeric characters that composer the values that will be (re-)recorded.

Important

Specifies a values greater than 1 for length, more of one sub-memory will be updated, of the following manner (examle): to the execute lbit.getNum(93, 4, "example", 3), the values stored in the sub-memories 4, 5 and 6 are update, respectively, by 0, 9 and 3.

Example

local function upPlayerInfo(v) -- x, y, damage, speed
	local id = {1, 4, 7, 9}
	local le = {3, 3, 2, 1} -- length
	
	for i = 1, 4 do
		lbit.setNum(v[i], id[i], "player", le[i])
	end
end

---

Come back to top

---

swapClass

• Description: re-record the name of a class.
• Return: none.

Structure

• swapClass(newClass, oldClass)
  • newClass (string): string that will be defined like class.
  • oldClass (string): class that will be replaced.

Example

local function corruptNight(evil)
	local newTxt = "good"
	local oldTxt = "evil"
	
	if evil then
		newTxt = "evil"
		oldTxt = "good"
	end

	-- classes names
	local names = {"villagers", "criters", "torrets", "pets"}
	
	local old, new = "", ""
	for i = 1, #names do
		old = names[i].."-"..oldTxt
		new = names[i].."-"..newTxt
	
		longBit.swapClass(new, old)
	end

end

---

Come back to top

---

update

• Description: update the values present in multiple sub-memories of one memory.
• Return: quantity of indexes that were assign to the sub-memories.

Structure

• update(class, values, indexes)
  • class (string): memory class whose sub-memories will be updated.
  • values (string matrix): values that will be assign to the sub-memories.
  • indexes (table): indexes of the sub-memories that will be updated (1-9).

Important

values and indexes must have the same quantity of values/indexes.

Note

The values width (length) is automatically defined.

Example

function BOOT()
	-- old: 68(y)  | new: 45(y)
	-- old: 1(gun) | new: 2(gun)
	if lbit.update("skins", {"65", "2"}, {4, 9}, 0) > 0 then
		trace("[ Memories updated to new version ]", 4)
	end

	-- [...]

---

Come back to top

---

getAll

• Description: get all content stored in a memory.
• Return: the values stored in memory, in string format.

Structure

• getAll(class, [full=false])
  • class (string): memory classes whose content will be getted.
  • full (boolean): specifies if the sub-memories empty from left must be shown.

Example

local function getScore()
	local score = {}

	for i = 6, 8 do
		score[i - 5] = lbit.getAll("ship"..(i - 5))
	end
	
	return table.unpack(score)
end

---

Come back to top

---

getBool

• Description: get and compare a values store in a sub-memory.
• Return: a boolean expressition indicating if the values getted is equal to equal.

Structure

• getBool(id, class, [equal=1], [length=1])
  • id (number): index of the sub-memory that will be compared.
  • class (string): memory class.
  • equal (number): value that will be compared with the value stored in sub-memory(ies).
  • length (number): quantity of characteres that composer the value.

Example

	-- [...]
	
	local spt = 256
	
	for i = 1, 9 do
		spt = 256 -- lock
		
		if lbit.getBool(i, "skins") then
			spt = 256 + i
		end
		
		spr(spt, 200, 80, 3, 2)
	end
	
	-- [...]

---

Come back to top

---

getClass

• Description: get a class already defined.
• Return: the class if it exist, otherwise it will return nil.

Structure

• getClass(id)
  • id (number): index of the memory whose class will be getted.

Example

local function checkClass(close)
	local info = ""
	
	for i = 0, 7 do
		if lbit.getClass(i) == nil then
			info = info..i.." - "
		end
	end
	
	trace("\n\n"..info.."\n\n", 3)
	
	if close then exit() end
end

---

Come back to top

---

getNum

• Description: get a values stored in one or more sub-memories.
• Return: the values getted.

Structure

• getNum(id, class, [length=1])
  • id (number): index of the sub-memory that will be getted.
  • class (string): memory class.
  • length (number): quantity of characteres that composer the value.

Example

-- [...]

function BOOT()
	-- [...]
	
	local ind = {1, 4, 7, 9}
	local var = {"x", "y", "hp", "skin"}
	local len = {3, 3, 2, 1}
	
	for i = 1, 4 do
		player[var[i]] = lbit.getNum(ind[i], "player", len[i])
	end
	
	-- [...]

---

Come back to top

---