1
flowchart TD
2
    AT["Alice 2 저작 도구<br/>(JAlice.java)"] -->|생성| W["World"]
3
    W -->|소유| SF["ScriptingFactory<br/>Jython 초기화, alice 패키지 로드"]
4
    W -->|소유| I["Interpreter<br/>월드별 Jython 엔진"]
5
    I -->|소유| NS["Namespace<br/>PyStringMap 서브클래스"]
6
    NS -->|이름 조회| WE["PyElement / PySandbox<br/>Alice 객체 프록시"]
7
    W -->|소유| SP["ScriptProperty<br/>캐싱 + .py 저장"]
8
    W -->|소유| SR["ScriptResponse<br/>매 프레임 EXEC_MULTIPLE"]
9
    W -->|소유| SDR["ScriptDefinedResponse<br/>프롤로그에서 EVAL"]
10

11
    subgraph UF["4가지 사용자 입력면"]
12
        S1["1. Sandbox Script<br/>우클릭 → Edit Script"]
13
        S2["2. ScriptResponse 블록<br/>드래그앤드롭 → 텍스트 입력"]
14
        S3["3. ScriptDefinedResponse 블록<br/>드래그앤드롭 → Response 표현식"]
15
        S4["4. ScriptComboWidget + ScratchPad<br/>하단 툴바 즉시 실행"]
16
    end
17

18
    S1 -->|"World.start() 시"| I
19
    S2 -->|"매 프레임 update(t)"| I
20
    S3 -->|"프롤로그(t) 평가"| I
21
    S4 -->|"유저 클릭 실행"| I
22
    I -->|"Py.exec / Py.eval"| JR["Jython 런타임"]
23
    JR -->|"__finditem__"| NS
24
    JR -->|"alice.* 함수"| PK["alice Python 패키지<br/>(Required/jython/Lib/alice/)"]
25
    PK -->|Java 상호운용| SF

1
전체 구조부터 보고 싶다?
2
  → 01-architecture.md     (Jython 부트스트랩, CompileType, World.start())
3
  → 05-behind-the-scenes.md (Java 클래스 전체 인벤토리)
4

5
이름이 어떻게 Alice 오브젝트에 연결되는지 궁금하다?
6
  → 02-name-resolution.md  (Namespace → PyElement 전 과정, PySandbox 변수 쓰기)
7

8
유저 입장에서 뭘 입력해야 하는지 알고 싶다?
9
  → 03-script-surfaces.md  (4가지 입력면 + 동작 안 함 확인)
10

11
API가 궁금하다?
12
  → 04-api-reference.md    (alice.* 함수 전수 + 버그 목록)
13

14
월드 파일을 뜯어보고 싶다?
15
  → 06-file-format-a2w.md  (a2w ZIP 구조, 저장/로드)
16
  → 07-file-format-a2c.md  (a2c 갤러리 오브젝트)
17
  → 08-element-data-xml.md (elementData.xml 스키마)
18
  → 09-storing-scripts.md   (ScriptProperty, .py 파일 저장)
19

20
블록이 어떻게 생성되는지 알고 싶다?
21
  → 10-drag-and-drop.md    (팔레트 → ResponsePrototype → Element)
22

23
실전 문제 해결이 필요하다?
24
  → 11-troubleshooting.md  (로딩 실패, 폰트, 변수, a2w 직접 수정)

1
# Script의 API 참조 — 실제로는 동작하지 않지만 구조는 이렇다
2

3
import alice
4

5
# 이름으로 접근 가능한 객체
6
bunny.color = alice.red
7
bunny.opacity = 0.5
8

9
# 애니메이션 함수
10
alice.MoveAnimation(subject=bunny, direction=alice.forward, amount=2, duration=2)
11
alice.SayAnimation(subject=bunny, what="Hello!")
12

13
# 제어 흐름
14
alice.DoInOrder(
15
    alice.MoveAnimation(subject=bunny, amount=1, duration=1),
16
    alice.TurnAnimation(subject=bunny, direction=alice.left, amount=0.25),
17
)
18

19
# 센서
20
if alice.keyboard.isKeyPressed(alice.keyboard.VK_SPACE):
21
    print("Space pressed!")

1
sequenceDiagram
2
    participant JVM as JVM
3
    participant SF as ScriptingFactory<br/>(jython.ScriptingFactory)
4
    participant JY as Jython 런타임
5
    participant AT as 저작 도구
6
    participant W as World
7
    participant I as Interpreter
8

9
    JVM->>SF: new ScriptingFactory()
10
    SF->>JY: PySystemState.initialize(preProperties, ...)
11
    Note over SF,JY: python.home = Required/jython/
12
    SF->>JY: alice/__init__.py 읽기 및 컴파일
13
    SF->>JY: Py.exec(code, builtins, builtins)
14
    Note over SF,JY: alice.* 이름을 builtins에 주입<br/>(전체 alice를 모든 Interpreter가 공유)
15

16
    AT->>W: new World()
17
    AT->>W: setScriptingFactory(SF)
18
    W->>SF: manufactureInterpreter()
19
    SF-->>I: new Interpreter(this)
20
    I->>I: new Namespace() + new PyModule("main", dict)
21
    W->>I: setWorld(this)
22
    I->>I: Namespace.setWorld(world) → clear() + setWorld()

1
flowchart LR
2
    E["Element.compile(script, source, type)"] --> EW["getWorld().compile(...)"]
3
    EW --> WI["getInterpreter().compile(...)"]
4
    WI --> PY["Py.compile_flags(script, pathname, CompileMode, flags)"]
5
    PY --> JC["jython.Code(PyCode, CompileType)"]
6

7
    E2["Element.eval(code)"] --> EW2["getWorld().eval(code)"]
8
    EW2 --> WI2["getInterpreter().eval(code)"]
9
    WI2 --> PYE["Py.eval(code.getPyCode(), ns, ns)"]
10

11
    E3["Element.exec(code)"] --> EW3["getWorld().exec(code)"]
12
    EW3 --> WI3["getInterpreter().exec(code)"]
13
    WI3 --> PYX["Py.exec(code.getPyCode(), ns, ns)"]

1
sequenceDiagram
2
    participant U as 유저가 Play 클릭
3
    participant W as World
4
    participant I as Interpreter
5
    participant NS as Namespace
6
    participant JB as Jython
7
    participant WOBJ as Alice 객체들
8

9
    U->>W: start()
10
    W->>I: start()
11
    I->>NS: resetNamespace() → clear() + setWorld()
12
    W->>W: script.getCode(EXEC_MULTIPLE)
13
    W->>I: exec(code)
14
    I->>JB: Py.exec(pyCode, ns, ns)
15
    JB->>NS: __finditem__("bunny")
16
    NS->>NS: 로컬에도 없고, 월드 이름도 아님
17
    NS->>WOBJ: m_pyWorld.__findattr__("bunny")
18
    WOBJ-->>NS: PyElement(bunny)
19
    NS-->>JB: PyElement
20
    JB->>PyElement: bunny.color = red
21
    PyElement->>WOBJ: property.set(red)
22

23
    loop 매 프레임
24
        W->>W: schedule()
25
        W->>W: scheduleBehaviors(t)
26
        Note over W: 모든 Sandbox behavior 실행
27
    end

1
classDiagram
2
    class Response {
3
        +ScriptProperty script
4
        +manufactureRuntimeResponse()
5
    }
6
    class ScriptResponse {
7
        +update(t): exec(script, EXEC_MULTIPLE)
8
    }
9
    class ScriptDefinedResponse {
10
        +prologue(t): eval(script, EVAL)
11
        -m_actual: RuntimeResponse
12
        +update(t): m_actual.update(t)
13
        +getTimeRemaining(t): m_actual.getTimeRemaining(t)
14
    }
15
    class RuntimeResponse {
16
        +prologue(t)
17
        +update(t)
18
        +epilogue(t)
19
    }
20

21
    Response <|-- ScriptResponse
22
    Response <|-- ScriptDefinedResponse
23
    ScriptDefinedResponse --> RuntimeResponse : m_actual에 위임

1
flowchart TD
2
    START["bunny.color = red"] --> NS["Namespace.__finditem__('bunny')"]
3
    NS --> C1["1. local PyStringMap 확인<br/>(Python local/global var)"]
4
    C1 -->|찾음| RET1["return PyObject"]
5
    C1 -->|없음| C2["2. 월드 이름과 일치?"]
6
    C2 -->|예| RETW["return m_pyWorld"]
7
    C2 -->|아니오| C3["3. World.lookup(key)"]
8
    C3 --> SB["Sandbox.lookup(key)"]
9
    SB --> STK["a. currentBehavior.stackLookup(key)<br/>(파라미터, 지역 변수)"]
10
    STK -->|찾음| REXPR["return Expression.getValue()"]
11
    STK -->|없음| DTL["b. currentBehavior.detailLookup(key)<br/>(behavior 속성)"]
12
    DTL -->|찾음| REXPR
13
    DTL -->|없음| C4["4. m_pyWorld.__findattr__('bunny')"]
14
    C4 --> PE["PyElement.__findattr_ex__('bunny')"]
15
    PE --> CH["a. getChildNamedIgnoreCase('bunny')"]
16
    CH -->|표현식 발견| CHVE["return expression.getValue()"]
17
    CH -->|element 발견| CHVN["return PyElement(descendant)"]
18
    CH -->|없음| PR["b. getPropertyNamedIgnoreCase('bunny')"]
19
    PR -->|찾음| PRV["return property.get()"]
20
    PR -->|없음| USCORE["c. name.startsWith('_')?"]
21
    USCORE -->|예| RETRY["이름[1:]로 재시도<br/>child → property → reflection"]
22
    USCORE -->|아니오| SUP["d. super.__findattr_ex__(name)<br/>(Java reflection fallback)"]

1
sequenceDiagram
2
    participant Script
3
    participant NS as Namespace
4
    participant PE as PyElement
5
    participant Elem as Alice Element
6

7
    Script->>NS: __finditem__("bunny")
8
    NS->>PE: __findattr_ex__("bunny")
9
    PE->>Elem: getChildNamedIgnoreCase("bunny")
10
    Elem-->>PE: Element(bunny Transformable)
11
    Note over PE: descendant is not Expression
12
    PE-->>NS: PyElement(bunny)
13
    NS-->>Script: PyElement(bunny)
14

15
    Script->>PE: bunny.color (읽기)
16
    PE->>Elem: getPropertyNamedIgnoreCase("color")
17
    Elem-->>PE: Color property
18
    PE->>PE: property.get() -> Color.RED
19
    PE-->>Script: PyColor(RED)
20

21
    Script->>PE: bunny.color = alice.red (쓰기)
22
    PE->>Elem: getPropertyNamedIgnoreCase("color")
23
    Elem-->>PE: Color property
24
    PE->>Elem: property.set(attr.__tojava__(Color.class))

1
1. Jython이 "bunny.color = alice.red" 파싱
2
   → bunny 평가: Namespace.__finditem__("bunny")
3

4
2. Namespace.__finditem__("bunny")
5
   → local dict: 없음
6
   → world name: "world" 아님
7
   → World.lookup("bunny"): m_currentBehavior == null → null 반환
8
   → m_pyWorld.__findattr__("bunny")
9

10
3. PyElement.__findattr_ex__("bunny")
11
   → getChildNamedIgnoreCase("bunny") → Element(bunny)
12
   → descendant is not Expression
13
   → return PyElement(bunny)
14

15
4. Python: bunny.color = alice.red
16
   → PyElement.__setattr__("color", red_pyobj)
17

18
5. PyElement.__setattr__("color", PyObject(alice.red))
19
   → getPropertyNamedIgnoreCase("color") → ColorProperty
20
   → attr.__tojava__(Color.class) → Java Color.RED
21
   → property.set(Color.RED)
22

23
6. "alice.red" 해석:
24
   from edu.cmu.cs.stage3.alice.scenegraph import Color
25
   red = Color.RED   # Java static field from constants.py

1
flowchart TD
2
    ALICE["Alice 2 실행"] -->|world 선택| CM["오른쪽 클릭"]
3
    CM -->|enableScripting=true| ES["Edit Script 메뉴"]
4
    ES --> SES["ScriptEditor 창<br/>여러 줄 코드 입력"]
5
    SES -->|"World.start()시"| EXEC1["EXEC_MULTIPLE 1회 실행"]
6

7
    ALICE -->|ResponseEditor| PALL["블록 팔레트"]
8
    PALL -->|드래그| SR["ScriptResponse 블록"]
9
    SR --> SRIN["script 필드에 코드 입력"]
10
    SRIN -->|매 프레임| EXEC2["EXEC_MULTIPLE 실행"]
11

12
    PALL -->|드래그| SDR["ScriptDefinedResponse 블록"]
13
    SDR --> SDRIN["Response 반환 표현식 입력"]
14
    SDRIN -->|프롤로그 1회| EVAL["EVAL"]
15

16
    ALICE -->|하단 UI| CW["ComboWidget + ScratchPad"]
17
    CW -->|한 줄 입력 + Go| EXEC3["EXEC_SINGLE 즉시 실행"]
18
    CW -->|여러 줄 + Perform All| EXEC4["EXEC_MULTIPLE 즉시 실행"]

1
Required/jython/Lib/alice/
2
  __init__.py        - 임포트, Keyboard, Mouse, Clock, copy(), exportToObj()
3
  animations.py      - 모든 애니메이션 + 제어 흐름 함수
4
  constants.py       - 색상, 방향, 스타일, HowMuch
5
  linearalgebra.py   - Vec3, dot(), cross()
6
  pinchgloves.py     - Pinch Gloves 하드웨어 연동 (직렬 COM 포트)

1
v = alice.Vec3(1, 2, 3)
2
v2 = alice.Vec3(4, 5, 6)
3
v + v2       # Vec3(5, 7, 9)
4
v * 2        # Vec3(2, 4, 6)
5
v.getLength()       # 3.74
6
alice.dot(v, v2)    # 32
7
alice.cross(v, v2)  # Vec3(-3, 6, -3)

1
def ScriptAction(fcn, args=(), kws={}):
2
    if type(fcn) == str:
3
        # 문자열 → ScriptResponse (매 프레임 실행)
4
        sr = ScriptResponse()
5
        sr.script.set(fcn)
6
        return sr
7
    else:
8
        # Callable → ApplyResponse (1회 호출)
9
        return ApplyResponse(fcn, args, kws)

1
alice.MoveAnimation(
2
    subject=bunny,
3
    amount=lambda: alice.random.random() * 5,
4
)

1
alice.copy(src, name="bunny2")              # 깊은 복사
2
alice.exportToObj(model, "bunny.obj")       # OBJ 내보내기
3
alice.ManufactureEach([bunny, snowman])     # ForEach 용 Variable

1
import pinchgloves
2
pinchgloves.AddPinchResponse(
3
    (pinchgloves.LEFT_THUMB, pinchgloves.LEFT_INDEX),
4
    on_pinch_callback, on_release_callback,
5
)
6
pinchgloves.SetDefaultPort("COM1")
7
pinchgloves.Start()

1
classDiagram
2
    class ScriptingFactory {
3
        <<interface>>
4
        +manufactureInterpreter()
5
        +getInterpreters()
6
        +setStdOut(OutputStream)
7
        +setStdErr(OutputStream)
8
    }
9
    class Interpreter {
10
        <<interface>>
11
        +setWorld(World)
12
        +start()/stop()
13
        +compile(String, Object, CompileType) Code
14
        +eval(Code) Object
15
        +exec(Code)
16
    }
17
    class Code {
18
        <<interface>>
19
        +getCompileType() CompileType
20
    }
21
    class CompileType {
22
        <<interface>>
23
        +EVAL / EXEC_SINGLE / EXEC_MULTIPLE
24
        +getMode() CompileMode
25
    }
26

27
    class jython_ScriptingFactory {
28
        +ScriptingFactory()
29
        -m_interpreters: Vector
30
    }
31
    class jython_Interpreter {
32
        -m_module: PyModule
33
        -m_dict: Namespace
34
        -m_world: World
35
    }
36
    class jython_Code {
37
        -m_pyCode: PyCode
38
        -m_compileType: CompileType
39
    }
40
    class Namespace {
41
        -m_world: World
42
        -m_pyWorld: PyElement
43
        -m_map: Hashtable
44
        +__finditem__(String) PyObject
45
        +java2py(Object) PyObject
46
    }
47
    class PyElement {
48
        -m_element: Element
49
        -m_namespace: Namespace
50
        +__findattr_ex__(String) PyObject
51
        +__setattr__(String, PyObject)
52
    }
53
    class PySandbox {
54
        +__setattr__(String, PyObject)
55
    }
56

57
    ScriptingFactory <|.. jython_ScriptingFactory
58
    Interpreter <|.. jython_Interpreter
59
    Code <|.. jython_Code
60
    jython_Interpreter --> Namespace : 소유
61
    Namespace --> PyElement : 생성
62
    PyElement <|-- PySandbox

1
// 이름이 바뀐 Response 클래스들
2
ConditionalLoopSequentialResponse → WhileLoopInOrder
3
ConditionalSequentialResponse    → IfElseInOrder
4
CountLoopSequentialResponse      → LoopNInOrder
5
ForEachInListSequentialResponse  → ForEach
6
OrientationAnimation             → ForwardVectorAnimation
7
ParallelForEachInListSequentialResponse → ForEachTogether
8
ParallelResponse                 → DoTogether
9
ProxyForScriptDefinedResponse    → ScriptDefinedResponse
10
SequentialForEachInListSequentialResponse → ForEachInOrder
11
SequentialResponse               → DoInOrder
12
MetaResponse                     → CallToUserDefinedResponse
13

14
// 내비게이션
15
KeyboardNavigationBehavior → KeyboardNavigationBehavior
16
MouseNavigationBehavior    → MouseLookingBehavior
17

18
// 포즈
19
Pose        → Pose
20
PoseAnimation → PoseAnimation
21
KeyMapping  → KeyMapping

1
블록/Python 코드 → ScriptProperty.getCode()
2
  → owner.compile(script, owner, compileType)
3
    → World.compile()
4
      → Interpreter.compile()
5
        → Py.compile_flags(script, path, mode, flags) → PyCode
6
      → new Code(PyCode, CompileType)
7
    → Code 반환
8
  → Code 캐싱 (m_code)
9
→ exec(code) / eval(code)
10
  → World.exec() → Interpreter.exec()
11
    → Py.exec(pyCode, ns, ns) / __builtin__.eval(pyCode, ns, ns)

1
flowchart TD
2
    subgraph ZIP["world.a2w (ZIP Archive)"]
3
        EH["elementCountHint.txt - 진행률 힌트"]
4
        TN["thumbnail.png - 120x90 미리보기"]
5
        SP["script.py - World Sandbox script"]
6
        EX["elementData.xml - 루트 World 직렬화"]
7
        CAM["camera/"]
8
        LIT["light/"]
9
        GRD["ground/ + __ita__/ + texture/"]
10
        BEH["behavior0/ + __Unnamed0__/ + __Unnamed1__/"]
11
        MET["my first method/"]
12
    end
13
    EH --> LOAD["Element.load()"]
14
    SP --- EX
15
    EX --> CAM & LIT & GRD & BEH & MET
16
    style SP fill:#ff0,stroke:#a80
17
    style EX fill:#aef,stroke:#08a

1
sequenceDiagram
2
    participant User as 유저
3
    participant AT as AuthoringTool
4
    participant ST as ZipFileTreeStorer
5
    participant EL as World (Element)
6
    participant SP as ScriptProperty
7

8
    User->>AT: Ctrl+S / Save World
9
    AT->>AT: saveWorldToFile(file)
10
    AT->>AT: fireWorldSaving, saveTabs, saveCount
11
    AT->>AT: thumbnail 생성 (설정 시)
12
    AT->>ST: open(file) / parse central dir
13
    ST->>EL: world.store(storer, observer, map)
14
    EL->>EL: elementCountHint.txt 쓰기
15
    EL->>EL: thumbnail.png 등 map 쓰기
16
    EL->>EL: internalStore() 재귀
17
    loop 각 child
18
        EL->>ST: createDir + setCurrentDir
19
        EL->>EL: child.internalStore() 재귀
20
    end
21
    SP->>ST: getKeepKey -> create or keep script.py
22
    EL->>ST: write elementData.xml
23
    AT->>ST: close() - delete, reorder, write CD

1
sequenceDiagram
2
    participant AT as AuthoringTool
3
    participant LD as ZipFileTreeLoader
4
    participant EL as Element
5
    participant SP as ScriptProperty
6

7
    AT->>LD: new ZipFileTreeLoader().open(file)
8
    LD->>LD: read all entries to memory
9
    AT->>EL: Element.load(loader, externalRoot, observer)
10
    EL->>EL: read elementCountHint.txt
11
    EL->>EL: parse elementData.xml -> Class.forName -> instantiate
12
    SP->>SP: decodeObject -> read script.py -> set()
13
    loop 각 <child>
14
        EL->>EL: setCurrentDir -> recursive load -> addChild
15
    end
16
    EL->>EL: ReferenceResolver.resolve()
17
    AT-->>User: World loaded

1
flowchart TD
2
    subgraph ZIP["Bopper.a2c (ZIP Archive)"]
3
        EH["elementCountHint.txt\n3\n"]
4
        GD["galleryData.xml\n⭐ 갤러리 메타데이터"]
5
        TN["thumbnail.png\n갤러리 썸네일"]
6
        EX["elementData.xml\nModel (Bopper) 직렬화"]
7
        ITA["__ita__/\n  ├ elementData.xml\n  ├ indices.bin\n  └ vertices.bin"]
8
        MAT["Material #2_CL/\n  ├ elementData.xml\n  └ image.png"]
9
    end
10

11
    GD -->|갤러리 표시용| GV[GalleryViewer]
12
    EX -->|오브젝트 데이터| LOAD["Element.load()"]
13

14
    style GD fill:#fda,stroke:#a60

1
<?xml version="1.0" encoding="UTF-8"?>
2
<model>
3
    <name>bumperCars</name>
4
    <parts>3</parts>
5
    <physicalsize>29.95m x 6.2m x 31.29m</physicalsize>
6
    <methods/>
7
    <questions/>
8
    <sounds/>
9
</model>

1
<?xml version="1.0" encoding="UTF-8"?>
2
<element class="edu.cmu.cs.stage3.alice.core.Model"
3
    modelName="Bopper" name="bopper" version="2.2">
4
    <child filename="__ita__"/>
5
    <child filename="Material #2_CL"/>
6
    <property name="color"><red>1.0</red><green>1.0</green><blue>1.0</blue><alpha>1.0</alpha></property>
7
    <property class="java.lang.Double" name="opacity">1.0</property>
8
</element>