스크립트 API

StarLight는 프로젝트를 컴파일할 때 아래 전역 API를 스크립트에 넣어 줘요. NeonJS와 Rhino 프로젝트 모두에서 같은 이름으로 쓸 수 있어요. 켜져 있는 플러그인이 등록한 API도 함께 들어와요.

Api, Utils, FileStream, DataBase, Device, Bridge는 메신저봇과 호환되는 API이고, BotManager, Broadcast, App은 메신저봇 R의 API2와 비슷한 API예요.

답장과 프로젝트 제어: Api#

파일 보내기: MediaSharer, room.sendMedia#

이미지·동영상·파일을 채팅방에 보내요. 카카오톡 방에는 카카오톡의 공유 화면을 열어 보내고, 디버그룸에서는 채팅에 그 파일이 바로 보여요. 그래서 파일을 보내는 봇도 디버그룸에서 시험할 수 있어요.

files는 경로(/sdcard/..., file://...), http(s) URL, data URL, Base64 문자열(base64:...), Java byte[], NeonJS의 Uint8Array·ArrayBuffer, Bitmap(예: msg.image) 중 하나이거나 이들의 배열이에요. 형식은 내용으로 판별해요.

options는 { fileName, timeout, cache, headers, leave }예요. 모르는 키는 오타로 보고 거부해요.

보내기는 바로 반환하고 결과는 나중에 알려 줘요. NeonJS에서는 Promise라 await할 수 있고, Rhino에서는 CompletableFuture라 .join()으로 기다려요. 실패해도 예외 없이 ok: false로 끝나요.

export async function onMessage(msg) {
    if (msg.message === "!고양이") {
        const r = await MediaSharer.send(msg, "https://example.com/cat.jpg", { leave: "home" });
        if (!r.ok)
            msg.room.send("전송 실패: " + r.error);
    }
}

전송 설정(다운로드 제한 시간, 최대 파일 크기, 전송 후 동작, 캐시)은 앱의 설정 > 미디어 전송에 있어요.

로그: Log#

프로젝트 로그에 기록을 남겨요. 로그는 로그 탭과 에디터 서랍의 로그 탭에서 볼 수 있어요.

모든 메서드는 Log.i(message) 또는 Log.i(tag, message)로 불러요. NeonJS 프로젝트에서는 console.log() 등도 같은 로그에 남아요.

데이터 저장#

DataBase#

프로젝트 폴더의 data/ 안에 텍스트 파일로 저장해요. 파일 이름만 넘기면 돼요.

const raw = (() => {
    try { return DataBase.getDataBase("count.txt"); } catch { return "0"; }
})();
DataBase.setDataBase("count.txt", String(Number(raw) + 1));

FileStream#

기기의 아무 경로에나 읽고 써요. 경로는 절대 경로로 적어요(예: /sdcard/StarLight/shared/memo.txt).

Env#

프로젝트 폴더의 .env 파일에 적은 값을 읽어요. API 키처럼 코드에 직접 적고 싶지 않은 값을 두기에 좋아요.

# 주석
API_KEY=abcd1234
USER_NAME=별빛
GREETING="안녕하세요, ${USER_NAME}"

const key = Env.get("API_KEY");

• 한 줄에 이름=값으로 적어요. 이름은 영문자, 숫자, _만 쓸 수 있어요.
• "큰따옴표" 값과 따옴표 없는 값에서는 ${다른_이름}으로 앞에서 정의한 값을 끼워 넣을 수 있어요. '작은따옴표' 값은 적은 그대로예요.
• 형식이 틀리면 로그에 환경 변수 파일(…) 로드 실패가 남고 Env는 비어 있어요.
• 모든 값은 문자열이에요. .env를 고친 뒤에는 다시 컴파일해야 반영돼요.

기기와 앱#

Device#

Utils#

const doc = Utils.parse("https://example.com");
const title = doc.select("h1").first().text();

App, Platform#

알림과 위젯#

Notification#

기기에 알림을 띄우고, 나중에 내용을 바꾸거나 지워요.

const noti = Notification.create(1)
    .setTitle("봇 알림")
    .setText("새 메시지 10개")
    .onClick("확인", (id) => Log.i("눌림: " + id))
    .build();

noti.update("봇 알림", "새 메시지 11개");
noti.delete();

setTitle()과 setText()는 꼭 불러야 해요. lights(argb, onMs, offMs), onDismiss(fn)도 쓸 수 있어요.

HomeWidget#

홈의 스크립트 값 위젯에 값을 보여 줘요. 홈과 위젯을 보세요.

프로젝트 사이#

Broadcast.register("alert", (text) => Api.replyRoom("공지방", text));

Broadcast.send("alert", "점검이 끝났어요");

이벤트 방식: BotManager (메신저봇 API2)#

메신저봇 R의 API2와 같은 방식이에요. 프로젝트의 API 방식에 메신저봇 API2가 있어야 쓸 수 있고, NeonJS를 권장해요. 동작은 kbotdocs의 API2 문서를 따라요.

const bot = BotManager.getCurrentBot();

function onMessage(msg) {
    if (msg.content === "/핑") msg.reply("퐁");
}
bot.addListener(Event.MESSAGE, onMessage);

function onCommand(msg) {
    // "@더하기 4 7" → msg.command === "더하기", msg.args → ["4", "7"]
    if (msg.command === "더하기") msg.reply(Number(msg.args[0]) + Number(msg.args[1]));
}
bot.setCommandPrefix("@");
bot.addListener(Event.COMMAND, onCommand);

• Event.Activity.*, Event.TICK, Event.BATTERY_LEVEL_CHANGED 상수도 있지만 StarLight에서는 불리지 않아요. 스크립트 전용 화면이 없기 때문이에요.
• bot: on/addListener, prependListener, off/removeListener, removeAllListeners, listeners, getListenersMap, send(방, 메시지)(방은 이름, ID, getRooms()의 방), canReply, markAsRead, setCommandPrefix, getName, getRootPath, getPower/setPower, compile, unload
• BotManager: getCurrentBot, getBot(이름)(컴파일되지 않았으면 null), getBotList, getBotNames, getBotCount, getRooms, getPower/setPower, compile, compileAll, prepare, prepareAll, isCompiled, unload
• BotManager.getRooms()는 지금까지 메시지를 받은 방의 목록이에요. 각 방에 name, channelId, isGroupChat, send(message), markAsRead()가 있어요.
• 메신저 패키지를 고르는 packageName 인자는 받기만 하고 아직 쓰지 않아요.

언어마다 다른 전역#